samagotchi 0.152.0 → 0.154.0

data/lib/samagotchi/title_command.rb

@@ -9,7 +9,7 @@ module Samagotchi
   # `/title --clear` drops it, and the lists show the first message again.
   # Anyone who may send the session a command may name it (a parent agent
   # its delegates too). It doesn't save: its host saves a changed result at
-  # once (Worker, the REPL). It runs mid-turn as well (anytime): the
+  # once (Worker). It runs mid-turn as well (anytime): the
   # worker's save takes the session's lock and writes a running turn's
   # checkpoint, as a turn's own saves do.
   class TitleCommand
@@ -28,7 +28,7 @@ module Samagotchi
     # @return [Array(String, Boolean, Symbol)] the reply, whether the
     #   title changed, and :ok or :error
     def run(args)
-      session = @engine.session or return ["no session yet", false, :error]
+      session = @engine.session or return [Session::NONE_YET, false, :error]
       text = args.to_s.gsub(/\s+/, " ").strip
       return [listing(session), false, :ok] if text.empty?
       # "--clear and more" is a slip, not a title.

data/lib/samagotchi/tool_runner.rb

@@ -6,6 +6,7 @@ require_relative "row_refs"
 require_relative "file_ref"
 require_relative "guardrails"
 require_relative "vision_context"
+require_relative "degrade"
 require_relative "log"
 require_relative "edit_preview"
 require_relative "tool_output_cut"
@@ -234,12 +235,12 @@ module Samagotchi
     # default isn't a window) or can't be read. It checks this result, not the
     # context already used.
     def window_guard
-      window = @window ? @window.call : (@kernel.tool_output_window if @kernel.respond_to?(:tool_output_window))
-      return nil unless window&.tokens&.positive? && window.source != :default
+      Degrade.call(:memory, "read_window_unknown") do
+        window = @window ? @window.call : (@kernel.tool_output_window if @kernel.respond_to?(:tool_output_window))
+        return nil unless window&.tokens&.positive? && window.source != :default
 
-      (window.tokens * MemoryBundle::IndexSize.chars_per_token / 2).floor
-    rescue StandardError
-      nil
+        (window.tokens * MemoryBundle::IndexSize.chars_per_token / 2).floor
+      end
     end
 
     # memory_read's cut line: the rest is in the memory's file, in the dir(s)
@@ -307,12 +308,12 @@ module Samagotchi
     # (MemoryBundle::IndexSize), nil for any other path, or when
     # memory.index_warn_tokens is off: other writes cost nothing.
     def memory_index_size(call)
-      scope = MemoryBundle::IndexSync.memory_scope(Tools::ToolPath.normalize(call[:path]))
-      return nil unless scope && MemoryBundle::IndexSize.warn_limit.positive?
+      Degrade.call(:memory, "index_size_unreadable") do
+        scope = MemoryBundle::IndexSync.memory_scope(Tools::ToolPath.normalize(call[:path]))
+        return nil unless scope && MemoryBundle::IndexSize.warn_limit.positive?
 
-      MemoryBundle::IndexSize.measure(scope)
-    rescue StandardError
-      nil
+        MemoryBundle::IndexSize.measure(scope)
+      end
     end
 
     # +result+ with the note memory_write gives when the refreshed index
@@ -556,15 +557,12 @@ module Samagotchi
 
     # A failing hook must not break the turn.
     def fire(name, event)
-      @kernel.hooks&.fire(name, event)
-    rescue StandardError
-      nil
+      Degrade.call(:hooks, "tool_hook_fire_failed", hook: name) { @kernel.hooks&.fire(name, event) }
     end
 
+    # A failing stream callback (a UI gone) must not break the call either.
     def emit(callback, event)
-      callback&.call(event)
-    rescue StandardError
-      nil
+      Degrade.call(:turn, "tool_event_callback_failed", type: (event[:type] if event.is_a?(Hash))) { callback&.call(event) }
     end
   end
 end

data/lib/samagotchi/toolkit.rb

@@ -249,10 +249,13 @@ module Samagotchi
       Kit.new(name: REVIEW, tools: REVIEW_TOOLS, groups: [])
     ].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
+    # What a toolkit declares, the Registry's filter: every registered tool,
+    # built-ins and plugin tools (chi.tool) alike (+all_core+, full), or the
+    # built-ins in +core+, and every tool an LLM context layer gates
+    # (forget_outputs), but for +removed+; +added+ declares any registered
+    # tool. A tool it leaves out without removing is reachable through the
+    # tool index (Registry#reachable_names). The index's own tools
+    # (find_tools, call_tool) are the Registry's to declare. +fallback+: why the session's
     # own toolkit couldn't be resolved (this is FULL then), nil when it was.
     # +prompt+: the kit's prompt text (its own or its base's), nil without.
     # +groups+: :all or the sorted source group names/globs it reaches.
@@ -272,7 +275,7 @@ module Samagotchi
       # @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?
+        return true if added.include?(entry.name) || !entry.layer.nil?
 
         all_core || core.include?(entry.name)
       end

data/lib/samagotchi/toolkit_binding.rb

@@ -38,6 +38,8 @@ module Samagotchi
       # config ones (#kits); Plugin::Registries appends to it.
       @plugin_kits = []
       @warned = []
+      # The tools #warn_stranded said once.
+      @stranded = []
     end
 
     # @return [Array<Toolkit::Kit>] the plugins' kits (Plugin::Registries' toolkits:)
@@ -192,13 +194,36 @@ module Samagotchi
       resolved = nil if resolved.everything?
       tools = @tools.call
       tools.reaching_kit = ->(group) { reaching_kit(group) }
-      return false if resolved == tools.toolkit
+      changed = resolved != tools.toolkit
+      if changed
+        tools.toolkit = resolved
+        @refresh_index.call
+        @reset_prompt.call
+      end
+      warn_stranded(tools)
+      changed
+    end
 
-      tools.toolkit = resolved
-      @refresh_index.call
-      @reset_prompt.call
-      true
+    # "web_x isn't declared on toolkit lean, and call_tool can't reach it
+    # this session: it arrived after the session's tools were set ·
+    # /toolkit add web_x declares it"
+    def self.stranded_notice(tool, toolkit)
+      "#{tool} isn't declared on toolkit #{toolkit}, and call_tool can't reach it this session: it arrived after " \
+        "the session's tools were set · /toolkit add #{tool} declares it"
+    end
+
+    # A notice (by its bundle, once per tool and worker) for each plugin
+    # tool that arrived mid-session on a kit that leaves it out without
+    # the tool index to reach it (Tools::Registry#stranded_names).
+    def warn_stranded(tools)
+      return unless tools.respond_to?(:stranded_names)
+
+      (tools.stranded_names - @stranded).each do |name|
+        @stranded << name
+        @notify.call(self.class.stranded_notice(name, tools.toolkit.name), :warn, tools[name]&.source.to_s, extra: {})
+      end
     end
+    private :warn_stranded
 
     # The first kit that resolves and reaches source group +group+, the
     # user's own (config's, the plugins') before the built-ins, so a hint

data/lib/samagotchi/toolkit_command.rb

@@ -3,6 +3,7 @@
 require "json"
 require_relative "cache_confirm"
 require_relative "toolkit"
+require_relative "session"
 
 module Samagotchi
   # /toolkit, the session's toolkit (Session#toolkit): with no argument,
@@ -40,7 +41,7 @@ module Samagotchi
       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"
+      session = @engine.session or raise ArgumentError, Session::NONE_YET
       before = @engine.toolkit_explained
       after = @engine.toolkit_explained(changed(before.toolkit, words.split))
       # Nothing the prompt carries changes (full +delegate on full): only

data/lib/samagotchi/toolkit_report_command.rb

@@ -241,7 +241,9 @@ module Samagotchi
     def grade(entry, kit, uses)
       kits = entry["kits"].is_a?(Hash) ? entry["kits"] : {}
       rules = kits[kit]
-      core_tools = Array(entry["core_tools"])
+      # The tools a kit's rules declare: the built-ins and the plugin tools
+      # (chi.tool) logged when the ask started (an older line has none).
+      core_tools = Array(entry["core_tools"]) | Array(entry["plugin_tools"])
       return ["ungradable", " (no rules logged for #{kit})"] unless rules.is_a?(Hash)
       return ["ungradable", " (tool calls not readable)"] if uses == :ungradable
 
@@ -259,8 +261,10 @@ module Samagotchi
     end
 
     # Whether a kit's rules declare +use+ (Toolkit::Resolved#declares?): a
-    # tool-index group by the kit's groups; a built-in by its core list;
-    # any other tool (a plugin's) unless the kit removes it.
+    # tool-index group by the kit's groups; a logged built-in or plugin
+    # tool (+core_tools+) by the kit's list (all of them on full) and its
+    # adds; any other (the index's own, a layer's, one that registered
+    # after the ask) unless the kit removes it.
     def covers?(rules, core_tools, use)
       return group_reached?(rules["groups"], use.group) if use.group && use.group != "chi"
 
@@ -276,8 +280,8 @@ module Samagotchi
       (declared & core_tools) - Array(rules["removed"])
     end
 
-    # +other+ declares no more built-ins and reaches no more groups than
-    # +rules+, and less of one of them.
+    # +other+ declares no more logged tools (built-ins and plugin tools)
+    # and reaches no more groups than +rules+, and less of one of them.
     def narrower?(other, rules, core_tools)
       mine = core_set(rules, core_tools)
       theirs = core_set(other, core_tools)

data/lib/samagotchi/toolkit_suggest.rb

@@ -31,8 +31,13 @@ module Samagotchi
     # A kit as the ask saw it: its name, classifier description and #rules.
     Candidate = Data.define(:name, :description, :rules)
     # +default+ is a Candidate (no description needed); +core_tools+ the
-    # built-ins registered when the ask started.
-    Snapshot = Data.define(:session_id, :turn_number, :default, :candidates, :core_tools, :state)
+    # built-ins registered when the ask started, +plugin_tools+ the plugin
+    # tools (chi.tool) registered then: a kit declares both by its rules.
+    Snapshot = Data.define(:session_id, :turn_number, :default, :candidates, :core_tools, :plugin_tools, :state) do
+      def initialize(session_id:, turn_number:, default:, candidates:, core_tools:, state:, plugin_tools: [])
+        super
+      end
+    end
     Suggestion = Data.define(:kit, :raw, :confidence, :decided)
     # One ask's outcome: its Suggestion, what on mode would do with it
     # (suggested, default, defer, below_threshold, invalid, no_judgment)
@@ -164,6 +169,7 @@ module Samagotchi
         decided: !!decided,
         would: would,
         core_tools: snapshot.core_tools,
+        plugin_tools: snapshot.plugin_tools,
         kits: [snapshot.default, *snapshot.candidates].to_h { |kit| [kit.name, kit.rules] }
       }
       Judged.new(suggestion: Suggestion.new(kit: selected, raw: raw, confidence: confidence, decided: !!decided),
@@ -319,10 +325,10 @@ module Samagotchi
     end
 
     # A resolved kit (Toolkit::Resolved) as frozen, JSON-ready rules, not
-    # a tool list: plugin and MCP tools may still be loading when the ask
-    # starts, and every kit declares a non-core tool anyway
-    # (Resolved#declares?), so the report expands these against the tools
-    # a turn really called (ToolkitReportCommand).
+    # a tool list: a plugin's replaced tools and MCP tools may still be
+    # loading when the ask starts, so the report expands these against
+    # the tools a turn really called (ToolkitReportCommand), the logged
+    # core_tools and plugin_tools by the same rule (Resolved#declares?).
     # @return [Hash{String => Object}]
     def self.rules(resolved)
       {

data/lib/samagotchi/tools/builtin_calls.rb

@@ -149,20 +149,23 @@ module Samagotchi
       end
 
       # A saved call as it ran (a reload, the stale-read pairing): a call_tool
-      # of a built-in ("chi/delegate", or a bare "delegate") is that
-      # built-in's call with via: "call_tool" when +output+ (its saved
-      # result) shows it ran as that built-in: its "[name]" lead, or, with
-      # no lead, an error that names it (refused by its name before the
-      # gate); any other call as it is (a call_tool that ran, refused or
-      # not, leads with "[call_tool]").
+      # of a chi tool, a built-in or a plugin's ("chi/delegate",
+      # "chi/web_search", or a bare "delegate") is that tool's call with
+      # via: "call_tool" when +output+ (its saved result) shows it ran as
+      # that tool: its "[name]" lead, or, with no lead, an error that names
+      # it (refused by its name before the gate; a plugin tool's only by
+      # its chi/ name, the one no MCP tool has); any other call as it is (a
+      # call_tool that ran, refused or not, leads with "[call_tool]"). No
+      # registry is asked: a reload without the plugin reads the same.
       # @param call [Hash] as #build gives it
       # @param output [String, nil]
       # @return [Hash]
       def unwrap_saved(call, output)
         return call unless call[:name] == VIA && call[:args].is_a?(Hash)
 
-        name = call[:args]["tool"].to_s.strip.delete_prefix(VIA_GROUP)
-        return call unless row(name) && ran_as?(output.to_s, name)
+        named = call[:args]["tool"].to_s.strip
+        name = named.delete_prefix(VIA_GROUP)
+        return call if name.empty? || name == VIA || !ran_as?(output.to_s, name, error: row(name) || named != name)
 
         build(name, saved_args(call[:args]["args"])).merge(via: VIA)
       end
@@ -183,9 +186,10 @@ module Samagotchi
         build(VIA, { "tool" => name, "args" => call[:args] })
       end
 
-      def ran_as?(output, name)
+      # +error+: whether a lead-less error that names the tool counts.
+      def ran_as?(output, name, error: true)
         lead = output[SAVED_LEAD, 1]
-        lead ? lead == name : output.start_with?("Error: #{name} ")
+        lead ? lead == name : error && output.start_with?("Error: #{name} ")
       end
 
       # call_tool's inner args as saved: an object, or its JSON text.

data/lib/samagotchi/tools/deferred_tools.rb

@@ -9,8 +9,8 @@ module Samagotchi
     # that loads tools (LLM::AnthropicMessages#loads_tools?): every tool the
     # session reaches but doesn't declare, so a find_tools hit can load it
     # and the model calls it by its own name. In order:
-    # 1. the built-ins the toolkit leaves out but doesn't remove
-    #    (Registry#reachable_names), in registry order;
+    # 1. the chi tools (built-ins and plugin tools) the toolkit leaves out
+    #    but doesn't remove (Registry#reachable_names), in registry order;
     # 2. the tool index's source tools (an MCP server's, by acts_as), only
     #    while call_tool is declared (ToolIndex#deferrable: sorted by name);
     # 3. every other name the conversation loaded (a find result's

data/lib/samagotchi/tools/delegate.rb

@@ -336,8 +336,10 @@ module Samagotchi
         when :timeout then "Error: the worker of session #{id[0, 8]} did not answer in time, so the message was not sent"
         else "Error: the message to session #{id[0, 8]} could not be written"
         end
+      rescue SessionManager::ScratchSession => e
+        "Error: session #{id[0, 8]}: #{e.message}"
       rescue SessionManager::OwnedByTUI
-        "Error: session #{id[0, 8]} is open in a chi REPL, which can't take a delegated message"
+        "Error: session #{id[0, 8]} is #{OwnerLock::TUI_BUSY}, which can't take a delegated message"
       rescue Session::AmbiguousId => e
         "Error: #{e.message}"
       end

data/lib/samagotchi/tools/delegate_cursor.rb

@@ -67,9 +67,9 @@ module Samagotchi
     end
 
     # The parent's cursors, one per child, in <parent dir>/delegates.json, so
-    # a respawned worker (or a REPL resuming the session) doesn't hand the
-    # model a reply it already had. Written by whoever owns the parent (its
-    # worker, or the REPL its kernel runs in), and by a continue moving
+    # a respawned worker (or a one-shot resuming the session) doesn't hand
+    # the model a reply it already had. Written by whoever owns the parent
+    # (its worker, or the one-shot its kernel runs in), and by a continue moving
     # delegates to the chain's new link (ChildMove, from another process):
     # a Mutex for the owner's turn thread vs its loop thread, and a flock on
     # LOCK_FILE between processes; the file is replaced whole.

data/lib/samagotchi/tools/delegate_wait.rb

@@ -143,7 +143,7 @@ module Samagotchi
       # "wake" (a delegate report, a turn of its own when idle), "queue" (a
       # report at its next step or turn, no wake) or "off" (only
       # delegate_result). Only a worker's session reads its children's rings
-      # (its Engine gives a relay); a REPL, a -p run or a scratch session
+      # (its Engine gives a relay); a -p --non-interactive run or a scratch session
       # never gets a report.
       # @param peers [Peers]
       # @return [String] "wake", "queue" or "off"

data/lib/samagotchi/tools/objectives_tool.rb

@@ -64,8 +64,8 @@ module Samagotchi
 
       def self.refusal(list, id, call)
         item = list.find(id)
-        return "Error: no objective #{id} (this session's: #{list.items.map(&:id).join(", ")}). Nothing was recorded." unless item
-        return "Error: #{id} was dropped, so nothing was recorded." if item.status == Objectives::DROPPED
+        return "Error: #{Objectives.unknown(id, list)}. Nothing was recorded." unless item
+        return "Error: #{Objectives.dropped(id)}. Nothing was recorded." if item.status == Objectives::DROPPED
 
         "Error: a move needs a note: what moved, in a line." if Objectives.clean(call[:note]).empty?
       end

data/lib/samagotchi/tools/registry.rb

@@ -41,14 +41,16 @@ module Samagotchi
       # What Tools::ToolIndex#declare registered: the entries of +source+
       # are the index's search and call tools, +call_name+ the call tool's
       # name, and +groups+ the source groups registered when the plugins
-      # loaded. +deferrable+ (→ the sources'
+      # loaded; +loaded+ the entries registered then (nil: whatever is
+      # registered now), which alone decide whether the index's tools are
+      # needed (Registry#index_needed?). +deferrable+ (→ the sources'
       # tools a host that loads tools may declare deferred) and +wrap+
       # (call → the call_tool call a direct call of one of them runs as, or
       # nil) are nil when nothing reaches them.
-      Index = Data.define(:source, :call_name, :groups, :deferrable, :wrap, :unreached) do
-        def initialize(source:, call_name:, groups:, deferrable: nil, wrap: nil, unreached: nil)
+      Index = Data.define(:source, :call_name, :groups, :deferrable, :wrap, :unreached, :loaded) do
+        def initialize(source:, call_name:, groups:, deferrable: nil, wrap: nil, unreached: nil, loaded: nil)
           super(source: source, call_name: call_name, groups: Array(groups).map(&:to_s).uniq.freeze,
-                deferrable: deferrable, wrap: wrap, unreached: unreached)
+                deferrable: deferrable, wrap: wrap, unreached: unreached, loaded: loaded&.dup&.freeze)
         end
 
         def unreached_tool(name) = unreached&.call(name)
@@ -116,18 +118,18 @@ module Samagotchi
         ordered(@entries.values.select { |entry| left_out?(entry, layers, toolkit) }).map(&:name)
       end
 
-      # The built-in +name+ names when the session's toolkit leaves it out
-      # but the tool index reaches it (#reachable_names).
+      # The tool +name+ names (a built-in or a plugin's) when the session's
+      # toolkit leaves it out but the tool index reaches it (#reachable_names).
       # @return [Entry, nil]
       def indexed(name, layers: [], toolkit: @toolkit)
         entry = self[name]
         entry if entry && call_offered?(toolkit) && soft?(entry, layers, toolkit)
       end
 
-      # The built-ins +toolkit+ leaves out of a turn under +layers+ that the
-      # tool index reaches (call_tool): not in its kit's list, but not
-      # removed either (remove:, --no-tool, /toolkit remove), with call_tool
-      # itself declared.
+      # The tools +toolkit+ leaves out of a turn under +layers+ that the tool
+      # index reaches (call_tool), built-ins and plugin tools alike: not in
+      # its kit's list, but not removed either (remove:, --no-tool, /toolkit
+      # remove), with call_tool itself declared. Never the index's own.
       # @return [Array<String>] in declaration order
       def reachable_names(layers: [], toolkit: @toolkit)
         return [] unless call_offered?(toolkit)
@@ -145,6 +147,25 @@ module Samagotchi
           .map(&:name)
       end
 
+      # The tools +toolkit+ leaves out of a turn under +layers+ that a
+      # plugin registered after the index was declared (chi.replace_tools)
+      # and that nothing reaches: call_tool isn't declared (the index's
+      # need is the load-time one, so the declared tools don't grow
+      # mid-session), nor removed by the user. /toolkit add declares one.
+      # @return [Array<String>] in declaration order
+      def stranded_names(layers: [], toolkit: @toolkit)
+        return [] if @index&.loaded.nil? || toolkit.nil? || toolkit.removed.include?(@index.call_name)
+        return [] if call_offered?(toolkit)
+
+        loaded = @index.loaded.map(&:name)
+        ordered(@entries.values.select { |entry| !loaded.include?(entry.name) && soft?(entry, layers, toolkit) })
+          .map(&:name)
+      end
+
+      # Every entry registered now, declared or not, in registration order.
+      # @return [Array<Entry>]
+      def registered = @entries.values
+
       # Every tool +source+ registered, declared or not (a plugin's tool set
       # changing: Plugin::ToolSpec.apply).
       # @return [Array<Entry>]
@@ -175,7 +196,7 @@ module Samagotchi
 
       # Declared by +toolkit+ (nil: every tool, full). The tool index's
       # tools are declared when they reach something, whatever the toolkit:
-      # a source registered at load, or a built-in it leaves out but
+      # a source registered at load, or a tool it leaves out but
       # doesn't remove (#index_needed?); unless it removes them.
       def declared?(entry, toolkit = @toolkit)
         if index_entry?(entry)
@@ -187,8 +208,10 @@ module Samagotchi
 
       def index_entry?(entry) = !@index.nil? && entry.source == @index.source
 
-      # From what the plugins registered at load and the toolkit alone, so
-      # the declared tools stay the same for a session's life. A built-in
+      # From what the plugins registered at load (Index#loaded) and the
+      # toolkit alone, so the declared tools stay the same for a session's
+      # life: a plugin tool registered later on a kit that leaves it out
+      # doesn't bring find_tools and call_tool in (#stranded_names). A tool
       # left out counts only while call_tool can reach it (not removed).
       def index_needed?(toolkit)
         return true if reached_groups?(toolkit)
@@ -198,10 +221,10 @@ module Samagotchi
       end
 
       # Whether the index's tools would reach something under +toolkit+,
-      # removed or not: a source registered at load, or a built-in the
-      # toolkit leaves out without removing it.
+      # removed or not: a source registered at load, or a tool (a built-in
+      # or a plugin's) the toolkit leaves out without removing it.
       def index_reaches?(toolkit)
-        reached_groups?(toolkit) || @entries.values.any? { |entry| soft?(entry, [], toolkit) }
+        reached_groups?(toolkit) || (@index.loaded || @entries.values).any? { |entry| soft?(entry, [], toolkit) }
       end
 
       def reached_groups?(toolkit)
@@ -218,11 +241,12 @@ module Samagotchi
         toolkit&.removed&.include?(entry.name) == true && index_reaches?(toolkit)
       end
 
-      # A built-in +toolkit+ leaves out of a turn under +layers+ without
-      # removing it.
+      # A tool +toolkit+ leaves out of a turn under +layers+ without removing
+      # it: a built-in or a plugin's, never one of the index's own (they are
+      # declared when they reach something) or a layer's (always declared).
       def soft?(entry, layers, toolkit)
-        !toolkit.nil? && entry.core? && entry.offered?(layers) && !toolkit.removed.include?(entry.name) &&
-          !toolkit.declares?(entry)
+        !toolkit.nil? && !index_entry?(entry) && entry.layer.nil? && entry.offered?(layers) &&
+          !toolkit.removed.include?(entry.name) && !toolkit.declares?(entry)
       end
 
       # Whether +toolkit+ declares the index's call tool.

data/lib/samagotchi/tools/send_note.rb

@@ -28,7 +28,8 @@ module Samagotchi
 
         result = NoteDelivery.deliver(id, text: content, source: "session", from_session: peers.session_id,
                                           from_cwd: peers.cwd, state_dir: peers.state_dir)
-        return "Error: session #{id[0, 8]} is open in a chi REPL, which can't take notes" unless result.delivered?
+        return "Error: session #{id[0, 8]}: #{result.refusal}" if result.scratch
+        return "Error: session #{id[0, 8]} is #{OwnerLock::TUI_BUSY}, which can't take notes" unless result.delivered?
 
         where = result.status == :queued ? "its worker adds it before its next turn" : "it has no worker now, so it waits for its next start"
         "Queued a note for session #{id[0, 8]}: #{where}. It does not start a turn there."

data/lib/samagotchi/tools/tool_index.rb

@@ -17,14 +17,15 @@ module Samagotchi
     # inputSchema, and call_tool, which calls one as <group>/<tool>.
     # A source (the mcp bundle, chi.tool_source) publishes its groups (an
     # MCP server each) and runs the calls; the index's own group, chi, is
-    # the built-ins the session's toolkit leaves out but doesn't remove
-    # (Registry#reachable_names), and a call_tool of one runs as that
-    # built-in (#unwrap, before the guardrail gate). The index searches the
+    # the tools the session's toolkit leaves out but doesn't remove, chi's
+    # built-ins and its bundles' (chi.tool) alike (Registry#reachable_names),
+    # and a call_tool of one runs as that tool (#unwrap, before the
+    # guardrail gate). The index searches the
     # groups, looks a call's tool up and checks it.
     #
     # The two tools are registered once, after the plugins load, and
     # declared per toolkit (Registry#declared?): when a source registered
-    # then, or the toolkit leaves a built-in reachable. The search tool's
+    # then, or the toolkit leaves a tool reachable. The search tool's
     # description has the source groups' lines as they were at load and a
     # chi line per toolkit (#refresh!): nothing a source publishes later
     # changes the request's tools, so the prompt cache keeps.
@@ -44,9 +45,10 @@ module Samagotchi
       # times one in its description.
       NAME_WEIGHT = 3
       PREVIEW_CHARS = 60
-      # The index's own group: chi's built-ins a toolkit leaves out.
+      # The index's own group: chi's tools (built-ins and bundles' chi.tool)
+      # a toolkit leaves out.
       CHI_GROUP = "chi"
-      CHI_SUMMARY = "chi's own tools not declared in this session"
+      CHI_SUMMARY = "chi's and its bundles' tools not declared in this session"
       # Group names a source can't publish: the index's own groups'.
       RESERVED_GROUPS = [CHI_GROUP].freeze
 
@@ -276,7 +278,7 @@ module Samagotchi
       end
 
       # Register the search and call tools in +registry+, once, after the
-      # plugins load (or without them: the built-ins a toolkit leaves out
+      # plugins load (or without them: the tools a toolkit leaves out
       # are reachable either way); +registry+ declares them per toolkit
       # (Registry::Index). A name another tool has is left out (a line in
       # +failures+).
@@ -285,6 +287,7 @@ module Samagotchi
         @registry = registry
         @described = description_lines(all_groups.reject { |group| own?(group) }).freeze
         @declared_group_names = @described.keys.freeze
+        loaded = registry.registered
         specs = [find_spec, call_spec]
         declared = specs.filter_map do |spec|
           if (taken = registry[spec.name])
@@ -299,7 +302,7 @@ module Samagotchi
         end
         registry.index = Registry::Index.new(source: SOURCE, call_name: CALL_NAME, groups: @declared_group_names,
                                              deferrable: -> { deferrable }, wrap: ->(call) { wrap(call) },
-                                             unreached: ->(name) { unreached_tool(name) })
+                                             unreached: ->(name) { unreached_tool(name) }, loaded: loaded)
         declared!(declared)
         declared.map(&:name)
       end
@@ -362,7 +365,7 @@ module Samagotchi
       # A call of the tool +name+ names, with +args+ typed by its schema,
       # run by its source. It fails closed: a tool that isn't the one
       # guardrails were given (#claimed) is refused, and so is one of the
-      # index's own (a built-in runs as itself, #unwrap, or not at all).
+      # index's own (a chi tool runs as itself, #unwrap, or not at all).
       def call(name, args)
         tool = lookup(name)
         return tool if tool.is_a?(String)
@@ -388,12 +391,12 @@ module Samagotchi
         source.run(tool, inner)
       end
 
-      # The built-in a call_tool +call+ names, as the call that runs in its
+      # The chi tool a call_tool +call+ names, as the call that runs in its
       # place (ToolRunner#run's first step, before the guardrail gate):
       # built from its arguments as a direct call would be
       # (BuiltinCalls.build), with via: "call_tool". The name is a chi tool
-      # (a bare one only while the toolkit reaches it), or chi/<built-in>
-      # for any registered built-in: one the toolkit removes or declares
+      # (a bare one only while the toolkit reaches it), or chi/<name> for
+      # any registered built-in or plugin tool: one the toolkit removes or declares
       # is then refused by its name before the gate (ToolRunner#left_out?),
       # with no hook or card. Nil, so the call runs as call_tool, when the
       # turn under +layers+ doesn't offer call_tool, for an MCP tool, a miss
@@ -429,8 +432,8 @@ module Samagotchi
       end
 
       # The name a request declares +name+'s tool by when it goes out
-      # deferred (Tools::DeferredTools): a reachable built-in's (by its
-      # name or chi/<name>), a deferrable source tool's acts_as (by it or
+      # deferred (Tools::DeferredTools): a reachable chi tool's, built-in or
+      # plugin (by its name or chi/<name>), a deferrable source tool's acts_as (by it or
       # <group>/<tool>). Nil for any other: declared, removed, unknown, or a
       # source tool that can't be deferred. Never waits for a start.
       # @return [String, nil]
@@ -549,7 +552,7 @@ module Samagotchi
       end
 
       # The wire names of +matches+ a request can declare deferred: a
-      # built-in of the index's own groups by its name, a source's tool by
+      # chi tool of the index's own groups by its name, a source's tool by
       # its acts_as when it is #deferrable.
       def loadable(matches)
         sourced = nil
@@ -578,16 +581,17 @@ module Samagotchi
 
       def own?(group) = RESERVED_GROUPS.include?(group.name)
 
-      # The registered built-in chi/<name> names, reachable or not.
+      # The registered chi tool chi/<name> names (a built-in or a plugin's,
+      # never the index's own), reachable or not.
       def builtin_named(name)
         return nil unless name.start_with?("#{CHI_GROUP}/")
 
         entry = @registry[name.delete_prefix("#{CHI_GROUP}/")]
-        entry if entry&.core?
+        entry unless entry.nil? || entry.source == SOURCE
       end
 
-      # The index's own groups: chi, the built-ins the Registry's toolkit
-      # leaves out but reaches (none: no group). Each tool's schema is its
+      # The index's own groups: chi, the tools (built-ins and plugin tools)
+      # the Registry's toolkit leaves out but reaches (none: no group). Each tool's schema is its
       # registered entry's (a config's execute description included), and
       # it acts as itself.
       # @return [Array<Group>]
@@ -698,8 +702,10 @@ module Samagotchi
         return same.first if same.size == 1
         return "Error: #{name} names #{same.map(&:full_name).join(" and ")}; call one as <group>/<tool>" if same.size > 1
 
-        # A built-in the session declares is no starting server's tool.
-        return "Error: #{name} is declared; call it directly" if @registry&.offered(name)&.core?
+        # A chi tool the session declares (a built-in or a plugin's) is no
+        # starting server's tool.
+        declared = @registry&.offered(name)
+        return "Error: #{name} is declared; call it directly" if declared && declared.source != SOURCE
 
         # A name with a group's <group>/ waits for that group only; any
         # other name (an acts_as) for every one starting.