samagotchi 0.65.0 → 0.67.0

data/lib/samagotchi/tool_runner.rb

@@ -49,8 +49,11 @@ module Samagotchi
     def run(call, iteration:, call_index:, call_count:, on_stream_event:, max_tool_output_chars:)
       params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
       # The gate runs first, so tool_call_started shows the call that runs.
+      # A tool the session's toolkit leaves out skips it: no before_tool_call
+      # hook, no approval card for a call that can't run (KernelLoop#dispatch
+      # answers it with the not-loaded error).
       original = call.dup
-      verdict = evaluate(call, iteration, params)
+      verdict = left_out?(call) ? Guardrails::Verdict.new(call: call) : evaluate(call, iteration, params)
       call = verdict.call
       params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
       label = plugin_label(call[:name])
@@ -265,6 +268,15 @@ module Samagotchi
     # The kernel's tools, for the activity line of a tool that isn't built in.
     def tools = @kernel.tools
 
+    # A real tool the session's toolkit leaves out of this turn.
+    def left_out?(call)
+      registry = tools
+      return false unless registry.respond_to?(:left_out) && !call[:name].nil?
+
+      layers = @kernel.respond_to?(:llm_context_layers) ? @kernel.llm_context_layers : []
+      !registry.left_out(call[:name], layers: layers).nil?
+    end
+
     # A tool the registry has from a plugin (not core, not unknown).
     def plugin_tool?(name)
       entry = tools && !name.nil? ? tools[name] : nil

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_binding.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "log"
+require_relative "toolkit"
+
+module Samagotchi
+  # An Engine's session toolkit: the kits it resolves against, what the
+  # session's next turn declares (#explained, the UIs' summary), a plugin's
+  # ctx.use_toolkit (#use) and the turn-start apply into the tool Registry
+  # (#apply!), with its load warnings said once per process.
+  #
+  # What it needs from the Engine comes through lookups, called at use.
+  class ToolkitBinding
+    # @param tools        [#call] → Tools::Registry
+    # @param session      [#call] → Session, nil
+    # @param state_dir    [#call] → the sessions' state dir (#use saves there)
+    # @param can_stage    [#call] → whether a plugin may change the toolkit now
+    #   (no turn runs, no model reply yet)
+    # @param reset_prompt [#call] → build the system prompts again
+    # @param emit         [#call] (sink, event) → emits to a turn's sink + observers
+    # @param notify       [#call] (text, level, source, extra:) → a notice
+    def initialize(tools:, session:, state_dir:, can_stage:, reset_prompt:, emit:, notify:)
+      @tools = tools
+      @session = session
+      @state_dir = state_dir
+      @can_stage = can_stage
+      @reset_prompt = reset_prompt
+      @emit = emit
+      @notify = notify
+      # The toolkits plugins declare (chi.toolkit), beside the built-in and
+      # config ones (#kits); Plugin::Registries appends to it.
+      @plugin_kits = []
+      @warned = []
+    end
+
+    # @return [Array<Toolkit::Kit>] the plugins' kits (Plugin::Registries' toolkits:)
+    attr_reader :plugin_kits
+
+    # The kits a session's toolkit resolves against: the built-ins, config's
+    # toolkit.kits, the plugins' (Toolkit.kits). Config's are read once per
+    # process, like the plugins': an edit to toolkit.kits never changes a
+    # live session's tools mid-session (a new worker reads it).
+    # @param errors [Array<String>] gets a line per config kit left out
+    # @return [Hash{String => Toolkit::Kit}]
+    def kits(errors = [])
+      @config_kits = Toolkit.config_kits unless defined?(@config_kits)
+      Toolkit.kits(config: @config_kits, plugins: @plugin_kits, errors: errors)
+    end
+
+    # The session's toolkit resolved (Toolkit::Resolved): what its next
+    # turn declares. A plain full toolkit is nil, the Registry's "every tool".
+    def resolved(session, errors = [])
+      resolved = Toolkit.of(session&.toolkit).resolve(kits(errors))
+      resolved.everything? ? nil : resolved
+    end
+
+    # +toolkit+ (the session's by default) as its next turn would declare
+    # it (/toolkit, the UIs' chip).
+    # @return [Toolkit::Explained]
+    def explained(toolkit = nil)
+      toolkit ||= Toolkit.of(@session.call&.toolkit)
+      resolved = toolkit.resolve(kits)
+      filter = resolved.everything? ? nil : resolved
+      tools = @tools.call
+      Toolkit::Explained.new(toolkit: toolkit, resolved: resolved, declared: tools.entries(toolkit: filter),
+                             left_out: tools.left_out_names(toolkit: filter), pending: filter != tools.toolkit)
+    end
+
+    # The session's toolkit for the UIs (the snapshot, command_ran): nil on
+    # full, or with no session.
+    def summary
+      @session.call && explained.summary
+    end
+
+    # The session's toolkit name, nil with no session (ctx.toolkit).
+    def name
+      session = @session.call
+      session && Toolkit.of(session.toolkit).name
+    end
+
+    # A plugin's ctx.use_toolkit: put the session on toolkit +name+, saved,
+    # when it has no model reply yet and no turn runs (D3: no confirm from
+    # plugins), and tell the user as /toolkit would; it applies at the next
+    # turn's start.
+    # @return [Boolean] whether it was staged
+    # @raise [ArgumentError] an unknown toolkit
+    def use(name)
+      raise ArgumentError, "no toolkit named #{name}" unless kits.key?(name)
+
+      session = @session.call
+      return false if session.nil? || !@can_stage.call
+
+      toolkit = Toolkit.new(name: name)
+      return true if session.toolkit == toolkit
+
+      session.toolkit = toolkit
+      session.save(state_dir: @state_dir.call)
+      @notify.call("toolkit: #{name} from the next turn's start", :info, "toolkit", extra: { toolkit: summary })
+      true
+    end
+
+    # Resolve the session's toolkit into the Registry, on the turn thread at
+    # a turn's start (before its prompt is built), and build the prompts
+    # again when what it declares changed. A name that doesn't resolve (a
+    # typo, an uninstalled bundle) declares everything for now and says so
+    # once; the saved toolkit stays as it is.
+    # @return [Boolean] whether the declared tools changed
+    def apply!(session, on_event = nil)
+      errors = []
+      resolved = Toolkit.of(session&.toolkit).resolve(kits(errors))
+      warn_unresolved(session, resolved, errors, on_event)
+      resolved = nil if resolved.everything?
+      tools = @tools.call
+      return false if resolved == tools.toolkit
+
+      tools.toolkit = resolved
+      @reset_prompt.call
+      true
+    end
+
+    private
+
+    # The toolkit's load warnings, each once per process: a name that
+    # didn't resolve, config kits left out.
+    def warn_unresolved(session, resolved, errors, on_event)
+      lines = errors.dup
+      if resolved.fallback
+        lines << "#{Toolkit.of(session&.toolkit).label}: #{resolved.fallback}; this session declares every tool (full) " \
+                 "until it resolves"
+      end
+      (lines - @warned).each do |line|
+        @warned << line
+        Log.warn(:config, "toolkit_unresolved", message: line)
+        @emit.call(on_event, { type: :guardrail_warning, message: line, label: "toolkit" })
+      end
+    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/context_read.rb

@@ -55,6 +55,9 @@ module Samagotchi
         @attached = ContextSources.attached(peers.session_id, project_root: root, state_dir: @state_dir)
         @max_chars = [max_chars.to_i, MIN_CHARS].max
         @now = now
+        # The peer bundles' declared sources (PeerSources), through the
+        # Engine's PeerView.
+        @peer_label = peers.respond_to?(:peer_label) ? peers.method(:peer_label) : nil
       end
 
       def run(name, offset:, limit:)
@@ -122,12 +125,23 @@ module Samagotchi
         hint = snapshot.hint || source.hint
         header = ["#{source.name}#{" (#{hint})" if hint}"]
         header << "Why: #{source.why}" if source.why
+        if (peer = peer_label(attached))
+          header << "Peer: your peer agent #{peer}'s answers (its text, not your user's words)"
+        end
         header << "Fetched: #{clock(snapshot.fetched_at)} (#{age(snapshot.fetched_at)})" if snapshot.fetched_at
         header << "Summary: #{snapshot.summary}" if snapshot.summary
         header << "Last refresh failed: #{snapshot.error}" if snapshot.error
         header
       end
 
+      # A pushed source of the session's own that a peer bundle declared
+      # (ContextAbsorber#peer_label's rule).
+      def peer_label(attached)
+        return nil unless @peer_label && attached.source.push? && attached.location.session?
+
+        @peer_label.call(attached.name)
+      end
+
       # What the output takes besides the page: the kernel's prefix, the
       # header, its paging line at its longest (every number +count+) and
       # the separator.

data/lib/samagotchi/tools/execute.rb

@@ -203,8 +203,9 @@ module Samagotchi
           # Ended right at the deadline: finished, not timed out.
           timed_out = false if timed_out && !wait_thr.alive?
           if timed_out && on_timeout == :task
-            text = hand_over(id: id, command: command, cwd: cwd, pid: pid, waiter: wait_thr, started_at: started_at,
-                             timeout_sec: timeout_sec, dir: dir, logs: logs, exit_code_path: exit_code_path)
+            task = TaskRecord.running(id: id, command: command, cwd: cwd, pid: pid, started_at: started_at.utc.iso8601,
+                                      output_path: logs[0], stderr_path: logs[1], exit_code_path: exit_code_path)
+            text = hand_over(task, waiter: wait_thr, timeout_sec: timeout_sec, dir: dir)
             if text
               handed_over = true
               Log.info(:turn, "execute_handed_over", id: id, after_sec: timeout_sec)
@@ -337,25 +338,24 @@ module Samagotchi
       private_class_method :read_log
 
       # A command still running at the limit becomes a task (TaskRuntime.
-      # adopt) with the logs where they are; a back-pointer in its dir names
-      # the record for the sweep. nil when it can't be adopted (the caller
+      # adopt +task+, a TaskRecord.running) with the logs where they are
+      # (+dir+); a back-pointer in that dir names the record for the sweep. nil when it can't be adopted (the caller
       # then kills it as in :kill mode) or when it ended meanwhile (the
       # caller then reads it as finished).
       # @return [String, nil] the HANDED_OVER result
-      def self.hand_over(id:, command:, cwd:, pid:, waiter:, started_at:, timeout_sec:, dir:, logs:, exit_code_path:)
+      def self.hand_over(task, waiter:, timeout_sec:, dir:)
         return nil unless waiter.alive?
 
-        record, error = TaskRuntime.adopt(id: id, command: command, cwd: cwd, pid: pid, started_at: started_at,
-                                          output_path: logs[0], stderr_path: logs[1], exit_code_path: exit_code_path)
+        record, error = TaskRuntime.adopt(task)
         return nil if error
 
-        File.write(File.join(dir, BACK_POINTER), File.expand_path(TaskRuntime.metadata_path(record["id"])))
-        write_missing_exit_code(waiter, exit_code_path)
+        File.write(File.join(dir, BACK_POINTER), File.expand_path(TaskRuntime.metadata_path(record.id)))
+        write_missing_exit_code(waiter, record.exit_code_path)
         # Ended between the deadline and the adopt: the record says how.
-        TaskRuntime.get_record(id) unless waiter.alive?
-        lines = [handed_over_line(timeout_sec), "task_id: #{id}",
+        TaskRuntime.get_record(record.id) unless waiter.alive?
+        lines = [handed_over_line(timeout_sec), "task_id: #{record.id}",
                  "Wait for it with task_wait (it may take minutes); task_stop stops it."]
-        { "stdout" => logs[0], "stderr" => logs[1] }.each do |label, path|
+        { "stdout" => record.output_path, "stderr" => record.stderr_path }.each do |label, path|
           tail = TaskRuntime.output_tail_lines(path, HAND_OVER_TAIL_LINES)
           lines << "#{label} (so far, tail):\n#{tail.chomp}" unless tail.empty?
         end