samagotchi 0.64.0 → 0.66.0

data/lib/samagotchi/toolkit.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require_relative "config"
+
+module Samagotchi
+  # A session's toolkit: which of the registered tools its prompts declare
+  # (docs/sessions.md, "Toolkits"). Saved in the session file as given
+  # ({"name" => "lean", "add" => [], "remove" => []}) when the session is
+  # created, kept by continues and forks, and never resolved again from
+  # config: a respawned worker declares what the session was created with.
+  # A session without one (a file from before toolkits) is on FULL.
+  #
+  # +name+ names a Kit (the built-ins, config's toolkit.kits, a plugin's
+  # chi.toolkit); +add+ and +remove+ are the session's own changes on top
+  # (--tool / --no-tool, /toolkit add|remove). #resolve against the kits
+  # known gives the Resolved the Registry filters by.
+  Toolkit = Data.define(:name, :add, :remove) do
+    def initialize(name:, add: [], remove: [])
+      super(name: name.to_s.strip, add: Toolkit.tool_names(add), remove: Toolkit.tool_names(remove))
+    end
+
+    # @return [Hash] the session file's "toolkit"
+    def to_file = { "name" => name, "add" => add, "remove" => remove }
+
+    # The plain form the snapshot and the web carry.
+    def to_h = { name: name, add: add, remove: remove }
+
+    # This toolkit with +tool+ declared (/toolkit add): a tool it removed
+    # comes out of +remove+ (back to its kit's), any other goes into +add+.
+    def adding(tool)
+      tool = tool.to_s
+      remove.include?(tool) ? with(remove: remove - [tool]) : with(add: (add + [tool]).uniq)
+    end
+
+    # This toolkit with +tool+ left out (/toolkit remove), the other way.
+    def removing(tool)
+      tool = tool.to_s
+      add.include?(tool) ? with(add: add - [tool]) : with(remove: (remove + [tool]).uniq)
+    end
+
+    # How the UIs name it: "lean", "lean +web_fetch -memory_write".
+    def label = [name, *add.map { |tool| "+#{tool}" }, *remove.map { |tool| "-#{tool}" }].join(" ")
+
+    def full? = name == Toolkit::FULL && add.empty? && remove.empty?
+
+    # The kit +name+ names, from +kits+ (Toolkit.kits), with the session's
+    # own +add+ and +remove+ on top. An unknown name, a base that is, or a
+    # cycle falls back to FULL with the reason in Resolved#fallback; the
+    # saved toolkit is untouched, so a reinstalled bundle gets it back.
+    # @param kits [Hash{String => Kit}]
+    # @return [Resolved]
+    def resolve(kits)
+      Toolkit.resolve_kit(name, kits).changed(add: add, remove: remove)
+    rescue Toolkit::Unresolved => e
+      Toolkit.resolve_kit(Toolkit::FULL, kits).changed(add: add, remove: remove).with(fallback: e.message)
+    end
+  end
+
+  class Toolkit
+    FULL = "full"
+    LEAN = "lean"
+    CHILD = "child"
+
+    # A name that can't be resolved (unknown, a cycle).
+    class Unresolved < StandardError; end
+
+    # A toolkit as a session's next turn would declare it (Engine
+    # #toolkit_explained): +toolkit+ as saved, +resolved+, the Registry
+    # +declared+ entries and the names it leaves out (+left_out+), and
+    # whether that isn't what the Registry declares now (+pending+: it
+    # applies at the next turn's start).
+    Explained = Data.define(:toolkit, :resolved, :declared, :left_out, :pending) do
+      # What the prompt carries of it: the declared names and, when it
+      # leaves tools out, the kit name the not-loaded line gives. Two equal
+      # keys build the same prompt (/toolkit's "no change", its cost).
+      def prompt_key = [declared.map(&:name), left_out.empty? ? nil : resolved.name]
+
+      # What the UIs show (the snapshot, command_ran): nil when it declares
+      # every tool on full (full, full +delegate), which has no chip.
+      def summary
+        return nil if toolkit.name == Toolkit::FULL && left_out.empty? && resolved.fallback.nil?
+
+        { name: toolkit.name, label: toolkit.label, left_out: left_out, fallback: resolved.fallback }
+      end
+    end
+
+    # Tool names as a list of unique, stripped strings.
+    def self.tool_names(names) = Array(names).map { |tool| tool.to_s.strip }.reject(&:empty?).uniq
+
+    # A named list of declared tools: +tools+ (:all, every built-in; or the
+    # built-in names) when it has no +base+, else its +base+'s with +add+
+    # and +remove+. +source+: "core", "config", or the bundle that declared
+    # it (chi.toolkit).
+    Kit = Data.define(:name, :base, :tools, :add, :remove, :source) do
+      def initialize(name:, base: nil, tools: nil, add: [], remove: [], source: "core")
+        super(name: name.to_s, base: base&.to_s, tools: tools == :all ? :all : Toolkit.tool_names(tools),
+              add: Toolkit.tool_names(add), remove: Toolkit.tool_names(remove), source: source.to_s)
+      end
+    end
+
+    # The built-ins `lean` declares: the file and shell tools, memories,
+    # the task tools (execute's hand-over, turn notes and task_wait's tail
+    # name the trio), questions, web_fetch, and context_read (core notes
+    # tell the model to call it).
+    LEAN_TOOLS = %w[
+      execute read write edit memory_read memory_write task_create task_wait task_get task_list task_stop
+      ask_user_question web_fetch context_read
+    ].freeze
+
+    BUILTIN_KITS = [
+      Kit.new(name: FULL, tools: :all),
+      Kit.new(name: LEAN, tools: LEAN_TOOLS),
+      # A delegate child: it reports to its parent (send_note; the
+      # delegated-by line names it) and leaves memory writes to it.
+      Kit.new(name: CHILD, base: LEAN, add: %w[send_note], remove: %w[memory_write])
+    ].to_h { |kit| [kit.name, kit] }.freeze
+
+    # What a toolkit declares, the Registry's filter: every built-in
+    # (+all_core+) or the ones in +core+, every plugin tool and every tool
+    # an LLM context layer gates (forget_outputs), but for +removed+;
+    # +added+ declares any registered tool. +fallback+: why the session's
+    # own toolkit couldn't be resolved (this is FULL then), nil when it was.
+    Resolved = Data.define(:name, :all_core, :core, :added, :removed, :fallback) do
+      def initialize(name:, all_core: false, core: [], added: [], removed: [], fallback: nil)
+        super(name: name.to_s, all_core: all_core, core: core.dup.freeze, added: added.dup.freeze,
+              removed: removed.dup.freeze, fallback: fallback)
+      end
+
+      # Every built-in and nothing removed: what no toolkit declares.
+      def everything? = all_core && removed.empty?
+
+      # @param entry [Tools::Registry::Entry]
+      def declares?(entry)
+        return false if removed.include?(entry.name)
+        return true if added.include?(entry.name) || !entry.core? || !entry.layer.nil?
+
+        all_core || core.include?(entry.name)
+      end
+
+      # This with +add+ declared and +remove+ left out, in that order of
+      # the kit's own words: a later change wins.
+      def changed(add: [], remove: [])
+        added = self.added - remove
+        removed = self.removed - add
+        with(added: (added + add).uniq, removed: (removed + remove).uniq)
+      end
+    end
+
+    # The session file's "toolkit": a Toolkit, nil for none (a file from
+    # before toolkits, or one that isn't a toolkit), which reads as FULL.
+    def self.from_file(value)
+      case value
+      when Hash
+        name = value["name"] || value[:name]
+        return nil if name.to_s.strip.empty?
+
+        new(name: name, add: value["add"] || value[:add], remove: value["remove"] || value[:remove])
+      when String, Symbol
+        value.to_s.strip.empty? ? nil : new(name: value)
+      end
+    end
+
+    # The toolkit a new session is stored on: config's toolkit.default, or
+    # toolkit.child for a delegate child; FULL when unset. As named: the
+    # worker resolves it (plugins' kits load there).
+    def self.configured(delegate: false)
+      name = Config.get(delegate ? "toolkit.child" : "toolkit.default").to_s.strip
+      new(name: name.empty? ? FULL : name)
+    end
+
+    # config.yml's toolkit.kits (a map of name => {base:, add:, remove:}),
+    # nil when it has none.
+    def self.config_kits
+      section = ConfigFile.section("toolkit")
+      section.is_a?(Hash) ? section["kits"] : nil
+    rescue StandardError
+      nil
+    end
+
+    # A new session's toolkit from chi --toolkit NAME / --tool / --no-tool
+    # (each repeatable, a comma list too): NAME (config's toolkit.default
+    # without one) with those tools added and left out; nil when none was
+    # given. A tool in both is left out.
+    def self.from_flags(name: nil, add: [], remove: [])
+      add = split_names(add)
+      remove = split_names(remove)
+      return nil if name.to_s.strip.empty? && add.empty? && remove.empty?
+
+      base = name.to_s.strip.empty? ? configured.name : name
+      new(name: base, add: add - remove, remove: remove)
+    end
+
+    def self.split_names(values) = tool_names(Array(values).flat_map { |value| value.to_s.split(",") })
+    private_class_method :split_names
+
+    # The toolkit a session is on: its own, or FULL without one.
+    def self.of(toolkit) = toolkit || new(name: FULL)
+
+    # What a toolkit change costs the prompt cache (CacheConfirm): the
+    # declared tools are the front of every request, so any change to them
+    # (or to the not-loaded line) is :full; nil when they stay the same.
+    # @param before [Object] what the prompt carries now (Explained#prompt_key)
+    # @param after [Object] what it would carry after the change
+    def self.cache_cost(before, after) = before == after ? nil : :full
+
+    # @return [Resolved] +name+'s kit through its bases
+    # @raise [Unresolved] unknown, or a cycle
+    def self.resolve_kit(name, kits, seen = [])
+      raise Unresolved, "no toolkit named #{name}" unless (kit = kits[name])
+      raise Unresolved, "toolkit #{name}'s bases make a cycle (#{(seen + [name]).join(" → ")})" if seen.include?(name)
+
+      base = if kit.base
+               resolve_kit(kit.base, kits, seen + [name])
+             else
+               Resolved.new(name: name, all_core: kit.tools == :all, core: kit.tools == :all ? [] : kit.tools)
+             end
+      base.changed(add: kit.add, remove: kit.remove).with(name: name)
+    end
+
+    # The kits known: the built-ins, then config's toolkit.kits, then the
+    # plugins' (chi.toolkit). A config kit with a built-in's name is left
+    # out (one it can't redefine) with a line in +errors+, and so is one
+    # that isn't a {base:, add:, remove:} map.
+    # @param config [Hash, nil] toolkit.kits
+    # @param plugins [Array<Kit>]
+    # @param errors [Array<String>] gets a line per kit left out
+    # @return [Hash{String => Kit}]
+    def self.kits(config: nil, plugins: [], errors: [])
+      kits = BUILTIN_KITS.dup
+      (config.is_a?(Hash) ? config : {}).each do |name, spec|
+        name = name.to_s
+        if kits.key?(name)
+          errors << "toolkit.kits.#{name}: #{name} is a built-in toolkit"
+        elsif !spec.is_a?(Hash)
+          errors << "toolkit.kits.#{name}: expected {base:, add:, remove:}"
+        else
+          spec = spec.transform_keys(&:to_s)
+          kits[name] = Kit.new(name: name, base: spec["base"] || FULL, add: spec["add"], remove: spec["remove"],
+                               source: "config")
+        end
+      end
+      plugins.each { |kit| kits[kit.name] ||= kit }
+      kits
+    end
+  end
+end

data/lib/samagotchi/toolkit_command.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "cache_confirm"
+require_relative "toolkit"
+
+module Samagotchi
+  # /toolkit, the session's toolkit (Session#toolkit): with no argument,
+  # the tools its next turn declares with their estimated tokens, the
+  # toolkit and the tools it leaves out; `/toolkit NAME` puts the session
+  # on another toolkit (its own adds and removes go), `/toolkit add TOOL`
+  # and `/toolkit remove TOOL` change one tool. A change is saved at once
+  # and applies at the next turn's start (Engine#apply_toolkit!). The
+  # declared tools are the front of every request, so once the session has
+  # a model reply a change asks first (CacheConfirm); --yes applies it.
+  class ToolkitCommand
+    NAME = "/toolkit"
+    USAGE = "usage: #{NAME} [NAME | add TOOL | remove TOOL]".freeze
+    # Characters per token for the estimates (context.chars_per_token's
+    # default; a listing, not a meter).
+    CHARS_PER_TOKEN = 4.0
+
+    # @param engine [Engine] #session, #toolkit_explained, #toolkit_kits,
+    #   #tools, #history?
+    # @param save [#call] saves the session after a change
+    def initialize(engine:, save:)
+      @engine = engine
+      @save = save
+    end
+
+    # @param args [String] what follows /toolkit (--yes anywhere)
+    # @param confirm [Boolean] ask before a change once the session has a
+    #   model reply (CacheConfirm); false applies it at once
+    # @return [Array(String, Boolean, CacheConfirm::Confirm|nil)] the reply,
+    #   whether the toolkit changed, and the confirm it asks for (nothing
+    #   changed then)
+    # @raise [ArgumentError] an unknown toolkit or tool, or bad words
+    def run(args, confirm: true)
+      words, yes = CacheConfirm.split(args, downcase: false)
+      return [listing(@engine.toolkit_explained), false, nil] if words.empty?
+
+      session = @engine.session or raise ArgumentError, "no session yet"
+      before = @engine.toolkit_explained
+      after = @engine.toolkit_explained(changed(before.toolkit, words.split))
+      # Nothing the prompt carries changes (full +delegate on full): not saved.
+      return [listing(before) + "\n(no change to what the next turn declares)", false, nil] if after.prompt_key == before.prompt_key
+
+      cost = Toolkit.cache_cost(before.prompt_key, after.prompt_key)
+      if confirm && !yes && CacheConfirm.needed?(cost: cost, history: @engine.history?, changed: !cost.nil?)
+        step = CacheConfirm.confirm(NAME, words)
+        return [[change_line(before, after), "The tools are the front of every request: the whole prompt is read " \
+                                             "again from them on.", step.text].join("\n"), false, step]
+      end
+
+      session.toolkit = after.toolkit
+      @save.call(session)
+      [[listing(after), "From the next turn's start (a running turn keeps its tools)."].join("\n"), true, nil]
+    end
+
+    # The toolkit, its declared tools with tokens, and the ones left out.
+    def listing(explained)
+      toolkit = explained.toolkit
+      lines = ["toolkit: #{toolkit.label}#{" (applies at the next turn's start)" if explained.pending}"]
+      if (fallback = explained.resolved.fallback)
+        lines << "  #{fallback}: every tool is declared (full) until it resolves"
+      end
+      declared = explained.declared
+      lines << "  declared (#{declared.size}, ~#{format_tokens(declared.sum { |entry| tokens(entry) })} tokens): " \
+               "#{declared.map { |entry| "#{entry.name} ~#{format_tokens(tokens(entry))}" }.join(", ")}"
+      left_out = explained.left_out
+      lines << "  not loaded: #{left_out.empty? ? "none" : left_out.join(", ")}"
+      lines << "  toolkits: #{@engine.toolkit_kits.keys.join(", ")}; #{USAGE.delete_prefix("usage: ")} changes it"
+      lines.join("\n")
+    end
+
+    private
+
+    # +toolkit+ after the words: NAME, add TOOL…, remove TOOL….
+    def changed(toolkit, words)
+      verb, *tools = words
+      case verb.downcase
+      when "add", "remove"
+        raise ArgumentError, "#{NAME} #{verb} needs a tool name\n#{USAGE}" if tools.empty?
+
+        tools.reduce(toolkit) do |kit, tool|
+          raise ArgumentError, "no tool named #{tool} in this session" unless @engine.tools.key?(tool)
+
+          verb.casecmp?("add") ? kit.adding(tool) : kit.removing(tool)
+        end
+      else
+        raise ArgumentError, "#{NAME} takes one toolkit name\n#{USAGE}" unless tools.empty?
+
+        kits = @engine.toolkit_kits
+        raise ArgumentError, "no toolkit named #{verb} (toolkits: #{kits.keys.join(", ")})" unless kits.key?(verb)
+
+        Toolkit.new(name: verb)
+      end
+    end
+
+    def change_line(before, after)
+      added = names(after) - names(before)
+      removed = names(before) - names(after)
+      parts = []
+      parts << "declares #{added.join(", ")}" unless added.empty?
+      parts << "leaves out #{removed.join(", ")}" unless removed.empty?
+      parts << "declares the same tools under its own name" if parts.empty?
+      "Switching to #{after.toolkit.label} #{parts.join("; ")}."
+    end
+
+    def names(explained) = explained.declared.map(&:name)
+
+    # A tool's schema in tokens, estimated from its JSON.
+    def tokens(entry) = (JSON.generate(entry.schema).length / CHARS_PER_TOKEN).round
+
+    def format_tokens(count) = count >= 1000 ? format("%.1fk", count / 1000.0) : count.to_s
+  end
+end

data/lib/samagotchi/tools/registry.rb

@@ -35,8 +35,15 @@ module Samagotchi
 
       def initialize
         @entries = {}
+        @toolkit = nil
       end
 
+      # The session's resolved toolkit (Toolkit::Resolved), which the lists
+      # below and #offered filter by; nil declares every tool (full). The
+      # Engine sets it at a turn's start, before the prompt is built, and
+      # only there: a request's declared tools never change mid-turn.
+      attr_accessor :toolkit
+
       # @return [Entry]
       def register(name, schema:, handler:, label: nil, preview: nil, targets: nil, refs: nil, source: "core", layer: nil)
         raise ArgumentError, "tool #{name} is already registered" if @entries.key?(name)
@@ -59,19 +66,40 @@ module Samagotchi
       # @return [Entry, nil]
       def offered(name, layers: [])
         entry = self[name]
-        entry if entry&.offered?(layers)
+        entry if entry&.offered?(layers) && declared?(entry)
+      end
+
+      # The entry +name+ names when the session's toolkit leaves it out (a
+      # real tool the model can't call here), nil otherwise.
+      # @return [Entry, nil]
+      def left_out(name, layers: [])
+        entry = self[name]
+        entry if entry&.offered?(layers) && !declared?(entry)
+      end
+
+      # The tools +toolkit+ (the session's by default) leaves out of a turn
+      # under +layers+.
+      # @return [Array<String>] in declaration order
+      def left_out_names(layers: [], toolkit: @toolkit)
+        ordered(@entries.values.select { |entry| entry.offered?(layers) && !declared?(entry, toolkit) }).map(&:name)
       end
 
+      # Every tool +source+ registered, declared or not (a plugin's tool set
+      # changing: Plugin::Api.apply_tools).
+      # @return [Array<Entry>]
+      def by_source(source) = @entries.values.select { |entry| entry.source == source }
+
       # The tools a turn offers is per turn: +layers+, the turn's LLM
       # context layers (LLMContextStrategy), adds the tools gated by them.
       # Without layers (none, the default) the list is what it always was.
       # @return [Array<String>] in declaration order
-      def names(layers: []) = entries(layers: layers).map(&:name)
+      def names(layers: [], toolkit: @toolkit) = entries(layers: layers, toolkit: toolkit).map(&:name)
 
-      # @return [Array<Entry>] in declaration order
-      def entries(layers: [])
-        core, added = @entries.values.select { |entry| entry.offered?(layers) }.partition(&:core?)
-        core + added.sort_by { |entry| [entry.source.to_s, entry.name] }
+      # @return [Array<Entry>] in declaration order: the ones the turn's
+      #   layers offer and the session's toolkit declares
+      #   (+toolkit+: another one's, for what a change would declare)
+      def entries(layers: [], toolkit: @toolkit)
+        ordered(@entries.values.select { |entry| entry.offered?(layers) && declared?(entry, toolkit) })
       end
 
       # @return [Array<Hash>] the schemas, in declaration order
@@ -81,6 +109,15 @@ module Samagotchi
         @entries.freeze
         super
       end
+
+      private
+
+      def declared?(entry, toolkit = @toolkit) = toolkit.nil? || toolkit.declares?(entry)
+
+      def ordered(entries)
+        core, added = entries.partition(&:core?)
+        core + added.sort_by { |entry| [entry.source.to_s, entry.name] }
+      end
     end
   end
 end

data/lib/samagotchi/turn_note.rb

@@ -136,13 +136,27 @@ module Samagotchi
     # text cut to its last STEP_CHARS. Never
     # sent: the payload builders send a system message's content, and the
     # copies for hooks, plugins and the recap drop it (AnswerDisplay.strip).
-    def empty(retries: 0, steps: [])
+    # +refusal+: the provider refused the answer (ModelResult#refusal:
+    # {category:} or {}), kept on the marker and said in the note.
+    def empty(retries: 0, steps: [], refusal: nil)
       marker = { retries: retries.to_i }
       marker[:steps] = steps.map { |step| capped_step(step) } unless steps.empty?
-      message("the previous turn ended with no visible answer (thinking only, or nothing). The user's last message is still unanswered.")
+      marker[:refusal] = refusal if refusal
+      what = if refusal
+               "the previous turn's answer was refused by the provider#{refusal_category(refusal)}"
+             else
+               "the previous turn ended with no visible answer (thinking only, or nothing)"
+             end
+      message("#{what}. The user's last message is still unanswered.")
         .merge(EMPTY_ANSWER => marker)
     end
 
+    # " (cyber)" for a refusal that names its category (either key type), else "".
+    def refusal_category(refusal)
+      category = (refusal[:category] || refusal["category"] if refusal.is_a?(Hash)).to_s.strip
+      category.empty? ? "" : " (#{one_line(category)})"
+    end
+
     def capped_step(step)
       step.slice(:role, :content, :thinking).to_h do |key, value|
         [key, key == :role || !value.is_a?(String) ? value : tail_of(value)]
@@ -167,9 +181,12 @@ module Samagotchi
     end
 
     # The notice every UI shows for a turn that ended with no answer:
-    # "no answer: the model returned nothing (after 1 retry)" (turn_events.js
-    # emptyAnswerLine words it the same).
-    def empty_answer_line(retries)
+    # "no answer: the model returned nothing (after 1 retry)", or for a
+    # +refusal+ (the marker's) "no answer: refused by the provider (cyber)"
+    # (turn_events.js emptyAnswerLine words it the same).
+    def empty_answer_line(retries, refusal: nil)
+      return "no answer: refused by the provider#{refusal_category(refusal)}" if refusal
+
       count = retries.to_i
       after = if count.positive?
                 " (after #{count} #{count == 1 ? "retry" : "retries"})"

data/lib/samagotchi/version.rb

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

data/lib/samagotchi/web/app.rb

@@ -566,6 +566,14 @@ module Samagotchi
         LLMContextStrategy.for_session(session, registry: host_registry)
       end
 
+      # A session's toolkit as its file names it ({name:, label:}), nil on
+      # full: without a worker nothing resolves it (a bundle's kits load in
+      # the worker), so the tools it leaves out aren't known here.
+      def toolkit_for(session)
+        toolkit = session.toolkit
+        toolkit && !toolkit.full? ? { name: toolkit.name, label: toolkit.label } : nil
+      end
+
       # A session's thinking level with where it came from and its own
       # (SettingExplained#summary), as its worker would resolve it; nil
       # when it can't be. Config and the registry only: no network.
@@ -848,6 +856,10 @@ module Samagotchi
         # native host), else the server's reading (an older worker, none).
         history = snapshot&.key?("reasoning_history") ? snapshot["reasoning_history"] : reasoning_history_for(session)
         session_json = session_json.merge(reasoning_history: history)
+        # Its toolkit when it isn't full (the tools chip): the worker's, which
+        # resolved it, else the name saved in the session file.
+        toolkit = snapshot&.key?("toolkit") ? snapshot["toolkit"] : toolkit_for(session)
+        session_json = session_json.merge(toolkit: toolkit)
         raw_messages = turn_snapshot ? turn_snapshot["messages"] : session.messages
         timing = timing_payload(id, live_metrics: snapshot && snapshot["metrics"], persisted: persisted)
         json_response(200, {
@@ -1944,7 +1956,8 @@ module Samagotchi
           did = step.is_a?(Hash) ? MessageParts.for_message(step, [], cwd: cwd) : nil
           { role: "assistant", content: "", parts: did } if did
         end
-        items << { role: "empty_answer", content: "", retries: (marker[:retries] || marker["retries"]).to_i }
+        refusal = marker[:refusal] || marker["refusal"]
+        items << { role: "empty_answer", content: "", retries: (marker[:retries] || marker["retries"]).to_i, refusal: refusal }.compact
       end
 
       # The last turn failed and its prompt went back to the user: the

data/lib/samagotchi/web/public/activity.js

@@ -103,8 +103,11 @@ export function addStarted(model, event = {}, now = null) {
   return { row, created: true };
 }
 
+// A replayed running call a snapshot timed (its elapsed_ms so far) started
+// that long before +now+; any other replayed start is no clock.
 function markStart(row, event, now) {
   if (now !== null && !event.replayed) row.startedAt = now;
+  else if (now !== null && event.elapsed_ms != null) row.startedAt = now - Number(event.elapsed_ms);
   else delete row.startedAt;
 }
 

data/lib/samagotchi/web/public/annotate_actions.js

@@ -0,0 +1,109 @@
+// Annotation actions: a bundle's pills in the Annotate bar (chi.annotation,
+// docs/plugins.md). Each prepares a command line of its plugin with the
+// selection filled into its template under it:
+//
+//   /claude validate
+//   From your thinking:
+//   > the quoted line
+//
+// and fills the composer with it (the note goes under), or sends it at once
+// (send: true). The pills ride on the session's command listing (the
+// worker's snapshot), so a muted bundle's go with its command. Pure: no DOM.
+// A module of its own: static JS is cached at unversioned URLs, and a new
+// export on an old module would blank the page.
+
+import { quoteBlock } from "./annotations.js";
+
+// How many plugin pills the bar shows; the rest go behind "⋯".
+export const INLINE_ACTIONS = 3;
+
+// The session's commands' annotations, flattened in listing order: {label,
+// line, template, send, command, anytime, source}. anytime: the command
+// runs mid-turn (a send pill needs it while a turn runs).
+export function annotationActions(commands) {
+  const out = [];
+  for (const c of Array.isArray(commands) ? commands : []) {
+    if (!c || typeof c.name !== "string" || !Array.isArray(c.annotations)) continue;
+    for (const a of c.annotations) {
+      if (!a || typeof a.label !== "string" || !a.label || typeof a.line !== "string" || !a.line) continue;
+      out.push({
+        label: a.label,
+        line: a.line,
+        template: typeof a.template === "string" && a.template ? a.template : "{quote}",
+        send: a.send === true,
+        command: c.name,
+        anytime: c.mid_turn === "anytime" || c.anytime === true,
+        source: typeof c.source === "string" ? c.source : "",
+      });
+    }
+  }
+  return out;
+}
+
+// Whether two action lists draw the same pills (the bar redraws only on a
+// change).
+export function sameActions(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+// The selection as templates read it: {quote} the labelled block Annotate
+// makes (annotations.js quoteBlock), {text} the selection alone with the
+// same trimming (CRLF → LF, each line's trailing blanks, blank lines at
+// either end; indentation kept), {source} where it came from (answer,
+// thinking, step, tool, user). null when it holds no text.
+export function selectionFields(raw, source = {}) {
+  const quote = quoteBlock(raw, source);
+  if (!quote) return null;
+  const lines = String(raw ?? "").replace(/\r\n?/g, "\n").split("\n").map((l) => l.replace(/\s+$/, ""));
+  while (lines.length && !lines[0]) lines.shift();
+  while (lines.length && !lines[lines.length - 1]) lines.pop();
+  return { quote, text: lines.join("\n"), source: source.kind || "answer" };
+}
+
+// +template+ with {quote}, {text} and {source} filled from +fields+; any
+// other {x} stays as written.
+export function fillTemplate(template, fields) {
+  return String(template ?? "").replace(/\{(quote|text|source)\}/g, (_, key) => String(fields?.[key] ?? ""));
+}
+
+// The line the pill prepares: its command line, the filled template under it.
+export function actionLine(action, fields) {
+  return `${action.line}\n${fillTemplate(action.template, fields)}`;
+}
+
+// The composer's text after a fill pill (+line+: actionLine's):
+//   - empty: the line;
+//   - it already starts with the same command line: the filled part is
+//     appended (several selections collect under one command);
+//   - another draft: the line on top, the draft under it, after a blank line
+//     (nothing leaves chi without a click on Send).
+export function composerWithAction(value, action, line) {
+  const draft = String(value ?? "");
+  if (!draft.trim()) return line;
+  const filled = line.slice(action.line.length + 1);
+  if (draft.trimStart().split("\n")[0].trim() === action.line) {
+    const before = draft.replace(/\s+$/, "");
+    return `${before}\n\n${filled}`;
+  }
+  return `${line.replace(/\s+$/, "")}\n\n${draft.replace(/^\s*\n/, "")}`;
+}
+
+// Whether a pill can be clicked: a fill pill always; a send pill while a
+// turn runs only when its command runs mid-turn (anytime), else it would come
+// back busy.
+export function actionEnabled(action, running) {
+  return !action.send || !running || action.anytime;
+}
+
+// A pill's tooltip: its label and bundle, that a send pill sends at once,
+// and why it is disabled.
+export function actionTitle(action, running) {
+  const base = action.source ? `${action.label} (${action.source})` : action.label;
+  if (!actionEnabled(action, running)) return `${base}: ${action.command} waits for the turn to end`;
+  return action.send ? `${base}: sends at once` : base;
+}
+
+// The pills shown inline and the ones behind "⋯".
+export function splitInline(actions, max = INLINE_ACTIONS) {
+  return { inline: actions.slice(0, max), more: actions.slice(max) };
+}