samagotchi 0.98.0 → 0.99.0

data/lib/samagotchi/plugin/context.rb

@@ -48,7 +48,9 @@ module Samagotchi
     # :non_interactive), which ctx.frontend names for plugins.
     # +toolkit+ returns the session's toolkit name, +declared_tools+ the
     # tool names its next turn declares, +use_toolkit+ takes a name and
-    # returns whether it staged it (Engine#use_toolkit).
+    # returns whether it staged it (Engine#use_toolkit); +load_tools+ takes
+    # (names, bundle) and returns the wire names it staged
+    # (Engine#load_tools).
     # +cancel_controller+ takes (handler:) and returns the controller a
     # ctx.http call without cancel: uses, nil for none: an init task's own,
     # else the running turn's for work done for it (the turn's thread, or a
@@ -56,7 +58,7 @@ module Samagotchi
     # +cost+ returns the session's spend now (SessionMetrics::Cost).
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
                       :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
-                      :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit,
+                      :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit, :load_tools,
                       :cancel_controller, :cost, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
@@ -182,6 +184,23 @@ module Samagotchi
       # @raise [ArgumentError] a toolkit no one declared
       def use_toolkit(name) = !!@host.use_toolkit&.call(name.to_s)
 
+      # Load tools the session reaches but doesn't declare, so the model
+      # calls them by name (docs/plugins.md): built-in names, MCP tools'
+      # acts_as (mcp_fs_read) or <group>/<tool>. A hint, not access: the
+      # tools stay behind the same guardrails, and only a host that takes
+      # tool changes (api: anthropic) gets one; elsewhere nothing is sent.
+      # Called from before_turn, they load for that turn; anywhere else,
+      # from the next turn's start. Idempotent: a declared tool, one loaded
+      # before, a removed or unknown one is skipped.
+      # @param names [Array<String>]
+      # @return [Array<String>] the names staged (wire names)
+      # @raise [ArgumentError] +names+ isn't an Array
+      def load_tools(names)
+        raise ArgumentError, "load_tools takes an Array of tool names" unless names.is_a?(Array)
+
+        Array(@host.load_tools&.call(names.map(&:to_s), @bundle))
+      end
+
       # Whether the session is a `chi scratch` one (deleted when it ends).
       def scratch? = !!@host.scratch&.call
 

data/lib/samagotchi/prompt.rb

@@ -5,6 +5,7 @@ require_relative "prompt_literal_guard"
 require_relative "vision_context"
 require_relative "tool_response"
 require_relative "steer"
+require_relative "tool_loads"
 
 module Samagotchi
   # Formats a message list into a prompt string ready for the /completion endpoint.
@@ -48,6 +49,8 @@ module Samagotchi
     #   the model's answer (Thinking.native: Qwen's empty thought)
     # @return [Array(String, Array<String>)]
     def self.format_with_images(messages, profile: ModelProfile.default, vision: nil, prefill: "")
+      # A plugin's tool change (ToolLoads) is for a Messages host only.
+      messages = messages.reject { |message| ToolLoads.entry?(message) }
       plan = ImagePlan.new(messages, vision, data: :base64)
       images = []
       suffixes = messages.each_with_index.map { |m, index| image_lines(plan.items(m, index), profile, images) }

data/lib/samagotchi/testing/bundle.rb

@@ -352,6 +352,8 @@ module Samagotchi
       def questions = @recorder.questions
       def model_requests = @recorder.model_requests
       def toolkit_uses = @recorder.toolkit_uses
+      # Every ctx.load_tools call (ToolLoad: names, bundle).
+      def tool_loads = @recorder.tool_loads
       # Queue ask_model answers: a String, an exception, or a callable.
       def model_answers = @recorder.model_answers
 

data/lib/samagotchi/testing/host.rb

@@ -47,6 +47,7 @@ module Samagotchi
           toolkit: -> { recorder[:toolkit] },
           declared_tools: -> { recorder[:declared_tools] || tool_names.call },
           use_toolkit: ->(name) { recorder.use_toolkit(name, toolkits.call) },
+          load_tools: ->(names, bundle) { recorder.load_tools(names, bundle) },
           cancel_controller: ->(handler: false) { recorder[:cancelled] ? stopped : nil },
           cost: -> { cost(recorder[:cost]) }
         )

data/lib/samagotchi/testing/recorder.rb

@@ -12,6 +12,8 @@ module Samagotchi
     Notice = Data.define(:text, :level, :hook, :fallback_for)
     # Text put into the running turn (ctx.steer, event[:steer]).
     Steer = Data.define(:text, :hook)
+    # A ctx.load_tools call: the names given, and the bundle.
+    ToolLoad = Data.define(:names, :bundle)
     # A stop_turn or stop_generation (+kind+ :turn or :generation).
     Stop = Data.define(:kind, :reason, :hook)
     # An ask_model request: the request Context built (SideQuestion), its
@@ -32,13 +34,13 @@ module Samagotchi
       DEFAULTS = {
         session_id: "test-session", cwd: nil, messages: [], messages_partial: false, model_name: "test:model",
         model_key: "model", toolkit: "full", declared_tools: nil, frontend: :worker, scratch: false, setup: nil,
-        prompt_files: [], cancelled: false, state_dir: nil, running: true, toolkit_staged: true,
+        prompt_files: [], cancelled: false, state_dir: nil, running: true, toolkit_staged: true, load_tools_staged: nil,
         # ctx.cost: nil (zero), a Float (reported USD), a Hash of the parts
         # (reported:, estimated:, side:, known:) or a callable giving one.
         cost: nil
       }.freeze
 
-      attr_reader :notices, :cards, :steers, :stops, :questions, :model_requests, :toolkit_uses, :answers,
+      attr_reader :notices, :cards, :steers, :stops, :questions, :model_requests, :toolkit_uses, :tool_loads, :answers,
                   :model_answers, :values
 
       def initialize(**values)
@@ -53,6 +55,7 @@ module Samagotchi
         @questions = []
         @model_requests = []
         @toolkit_uses = []
+        @tool_loads = []
         @answers = []
         @model_answers = []
         @mutex = Mutex.new
@@ -127,6 +130,14 @@ module Samagotchi
         answer.respond_to?(:call) ? answer.call(entry) : answer
       end
 
+      # ctx.load_tools: recorded; every name is staged unless the test set
+      # load_tools_staged: (a list: those only).
+      def load_tools(names, bundle)
+        record(@tool_loads, ToolLoad.new(names: names, bundle: bundle))
+        staged = self[:load_tools_staged]
+        staged ? names & Array(staged) : names
+      end
+
       # ctx.use_toolkit: +known+ the toolkits chi and the plugins declare.
       # Staged (toolkit_staged:, true by default), the session is on it at
       # once, as chi saves it on the session (ToolkitBinding#use).

data/lib/samagotchi/tool_loads.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The tools plugins load (ctx.load_tools), staged until a turn's messages
+  # are built (Engine#turn_messages): then each bundle's names go into the
+  # conversation as one system entry of kind KIND, which a host that takes
+  # tool changes (LLM::AnthropicMessages#tool_changes?) receives as a
+  # tool_addition by reference. The names are wire names a request declares
+  # deferred (Tools::DeferredTools): a built-in's, a source tool's acts_as.
+  # Staging is idempotent: a name already staged is staged once.
+  class ToolLoads
+    KIND = "tool_change"
+    # The entry's key for what it adds: {add: [names], by: bundle}.
+    KEY = :tool_change
+
+    def initialize
+      @mutex = Mutex.new
+      @staged = {}
+    end
+
+    # Stage +names+ for bundle +by+.
+    # @return [Array<String>] the names newly staged
+    def stage(names, by:)
+      @mutex.synchronize do
+        taken = @staged.values.flatten
+        fresh = names.uniq - taken
+        (@staged[by.to_s] ||= []).concat(fresh) unless fresh.empty?
+        fresh
+      end
+    end
+
+    def any? = @mutex.synchronize { @staged.any? }
+
+    # The staged names per bundle, cleared.
+    # @return [Hash{String => Array<String>}]
+    def take
+      @mutex.synchronize do
+        staged = @staged
+        @staged = {}
+        staged
+      end
+    end
+
+    # The conversation entry for bundle +by+'s +names+.
+    def self.entry(names, by:)
+      { role: "system", kind: KIND, content: "[tools loaded: #{names.join(", ")} (#{by})]",
+        KEY => { add: names, by: by } }
+    end
+
+    # Whether +entry+ is one of #entry's (string or symbol keys).
+    def self.entry?(entry) = entry.is_a?(Hash) && (entry[:kind] || entry["kind"]).to_s == KIND
+
+    # The names +messages+' tool change entries added.
+    # @return [Array<String>]
+    def self.added(messages)
+      Array(messages).select { |entry| entry?(entry) }.flat_map do |entry|
+        change = entry[KEY] || entry[KEY.to_s] || {}
+        Array(change[:add] || change["add"]).map(&:to_s)
+      end
+    end
+  end
+end

data/lib/samagotchi/tool_response.rb

@@ -14,6 +14,8 @@ module Samagotchi
     # run's chi-owned id, ToolIds, and a strategy's edits by id,
     # LLMContextEdit); the prompt never renders them.
     SAVED_KEYS = %i[tool_params tool_labels tool_diffs tool_refs tool_ids edits].freeze
+    # The tools a chat result loaded (#single), saved with it.
+    LOADED = :loaded
     # A run's "[name]" lead: the name, then a newline, a space or the end.
     LEAD = /\A\[([^\]\s]+)\](?:\n| |\z)/
 
@@ -90,7 +92,8 @@ module Samagotchi
 
     # The chat loop's entry for one call: its capped output, paired with the
     # call by +tool_call_id+, and its chi-owned id (a one-id +ids+, as
-    # #joined's tool_ids).
+    # #joined's tool_ids); a find_tools hit's +loaded+ names (saved on every
+    # chat backend: a wire that loads tools renders them, LLM::AnthropicWire).
     def single(run, tool_call_id:, ids:)
       entry = { role: "tool_response", content: run.capped_output, tool_call_id: tool_call_id }
       entry[:images] = run.images if run.images&.any?
@@ -99,6 +102,7 @@ module Samagotchi
       entry[:tool_diffs] = run.diff if run.diff
       entry[:tool_refs] = run.refs if run.refs
       entry[:tool_ids] = ids
+      entry[LOADED] = run.loaded if run.loaded&.any?
       entry
     end
 

data/lib/samagotchi/tool_runner.rb

@@ -17,11 +17,13 @@ require_relative "memory_bundle/index_size"
 module Samagotchi
   # One call's result from ToolRunner#run, read by ToolResponse (the loops'
   # tool_response entries) and the loops' activity list. Fields a call didn't
-  # produce (images, shown_params, shown_label, refs, diff, output_file) are nil.
+  # produce (images, shown_params, shown_label, refs, diff, output_file,
+  # loaded) are nil. +loaded+: the tools a find_tools hit loads
+  # (Tools::ToolIndex::FoundText#loaded), by their wire names.
   ToolRun = Data.define(:output, :capped_output, :truncated, :activity, :images, :shown_params, :shown_label, :refs, :diff,
-                        :output_file) do
+                        :output_file, :loaded) do
     def initialize(output: nil, capped_output: nil, truncated: nil, activity: nil, images: nil, shown_params: nil,
-                   shown_label: nil, refs: nil, diff: nil, output_file: nil)
+                   shown_label: nil, refs: nil, diff: nil, output_file: nil, loaded: nil)
       super
     end
   end
@@ -150,7 +152,8 @@ module Samagotchi
       ToolRun.new(output: output, capped_output: capped, truncated: truncated, activity: result[:activity],
                   images: images&.any? ? images : nil,
                   shown_params: params && plugin_tool?(call[:name]) ? params : nil,
-                  shown_label: label, refs: refs.empty? ? nil : refs, diff: diff, output_file: output_file)
+                  shown_label: label, refs: refs.empty? ? nil : refs, diff: diff, output_file: output_file,
+                  loaded: result[:loaded])
     end
 
     private
@@ -317,29 +320,48 @@ module Samagotchi
     def layers = @kernel.respond_to?(:llm_context_layers) ? @kernel.llm_context_layers : []
 
     # The call its tool's entry unwraps it to (call_tool on a built-in),
-    # else the call as it is. One that fails runs as it is: call_tool then
-    # refuses a built-in (fail closed).
+    # else the call as it is. On a host that loads tools, a direct call of
+    # a source's tool by its acts_as runs as the call_tool call first
+    # (Registry::Index#wrap): call_tool's row, rules and approvals. One
+    # that fails runs as it is: call_tool then refuses a built-in (fail
+    # closed).
     def unwrapped(call)
       registry = tools
       return call unless registry.respond_to?(:offered) && !call[:name].nil?
 
+      call = wrapped(registry, call)
       registry.offered(call[:name], layers: layers)&.unwrap&.call(call, layers) || call
     rescue StandardError => e
       Log.warn(:turn, "tool_unwrap_failed", tool: call[:name].to_s, error: "#{e.class}: #{e.message}")
       call
     end
 
+    # +call+ as the call_tool call it runs as when it names a deferred
+    # source tool, on a host that loads tools; else as it is.
+    def wrapped(registry, call)
+      wrap = registry.respond_to?(:index) ? registry.index&.wrap : nil
+      return call unless wrap && loads_tools? && !registry.key?(call[:name])
+
+      wrap.call(call) || call
+    end
+
     # A call that can't run in this turn as it is, by its name: a real tool
     # the session's toolkit leaves out, or one reached through call_tool
-    # (via:) that the toolkit doesn't reach that way (a hook's rewrite).
+    # (via:) that the toolkit doesn't reach that way (a hook's rewrite). On
+    # a host that loads tools, a built-in the toolkit reaches runs by its
+    # own name (KernelLoop#dispatch takes it too).
     def left_out?(call)
       registry = tools
       return false unless registry.respond_to?(:left_out) && !call[:name].nil?
       return registry.indexed(call[:name], layers: layers).nil? if call[:via]
+      return false if loads_tools? && registry.indexed(call[:name], layers: layers)
 
       !registry.left_out(call[:name], layers: layers).nil?
     end
 
+    # Whether the turn's host loads tools (TurnSettings#loads_tools).
+    def loads_tools? = @kernel.respond_to?(:turn_settings) && @kernel.turn_settings&.loads_tools == true
+
     # 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/tools/builtin_calls.rb

@@ -166,6 +166,22 @@ module Samagotchi
         build(name, saved_args(call[:args]["args"])).merge(via: VIA)
       end
 
+      # A saved direct call of a deferred source tool (an MCP tool by its
+      # acts_as, on a host that loads tools) as the call_tool call it ran as
+      # (ToolIndex#wrap): a name that is no built-in, object args, and a
+      # result that leads with "[call_tool]". Any other call as it is. The
+      # tool is named by its acts_as (the call tool takes it as well).
+      # @param call [Hash] as #build gives it
+      # @param output [String, nil]
+      # @return [Hash]
+      def wrap_saved(call, output)
+        name = call[:name].to_s
+        return call if name.empty? || name == VIA || row(name) || !call[:args].is_a?(Hash)
+        return call unless output.to_s[SAVED_LEAD, 1] == VIA
+
+        build(VIA, { "tool" => name, "args" => call[:args] })
+      end
+
       def ran_as?(output, name)
         lead = output[SAVED_LEAD, 1]
         lead ? lead == name : output.start_with?("Error: #{name} ")

data/lib/samagotchi/tools/deferred_tools.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../tool_declarations"
+
+module Samagotchi
+  module Tools
+    # The tools a request declares deferred (defer_loading: true) on a host
+    # 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;
+    # 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
+    #    loaded:, a tool change's add:) that isn't declared: a stub (its
+    #    source is gone, or hasn't published yet), so the reference in the
+    #    history stays valid. The runner refuses its calls as any other.
+    # The list goes after the declared tools, outside the cached prefix's
+    # marks: a tool joining it (a late server) keeps the cache.
+    module DeferredTools
+      # One deferred tool: its wire name, description and input schema.
+      Deferred = Data.define(:name, :description, :schema)
+
+      STUB_DESCRIPTION = "Not available right now; find_tools finds it when it is."
+      STUB_SCHEMA = { "type" => "object", "properties" => {} }.freeze
+
+      module_function
+
+      # @param registry [Registry]
+      # @param conversation [Array<Hash>, nil] the request's (engine format)
+      # @param layers [Array<Symbol>] the turn's LLM context layers
+      # @return [Array<Deferred>]
+      def list(registry, conversation, layers: [])
+        deferred = builtins(registry, layers) + sourced(registry, layers)
+        taken = deferred.map(&:name)
+        loaded_names(conversation).each do |name|
+          next if taken.include?(name) || registry.offered(name, layers: layers)
+
+          taken << name
+          deferred << Deferred.new(name: name, description: STUB_DESCRIPTION, schema: STUB_SCHEMA)
+        end
+        deferred
+      end
+
+      # The names +conversation+ loaded, first reference first: a find
+      # result's loaded: (ToolResponse::LOADED), a tool change's add:.
+      # @return [Array<String>]
+      def loaded_names(conversation)
+        Array(conversation).flat_map do |entry|
+          names = entry[:loaded] || entry["loaded"]
+          change = entry[:tool_change] || entry["tool_change"]
+          names = change[:add] || change["add"] if change.is_a?(Hash)
+          Array(names).map(&:to_s)
+        end.uniq
+      end
+
+      def builtins(registry, layers)
+        return [] unless registry.respond_to?(:reachable_names)
+
+        registry.reachable_names(layers: layers).map do |name|
+          schema = ToolDeclarations.chat_schemas([registry[name].schema]).first
+          Deferred.new(name: name, description: schema[:description].to_s, schema: schema[:parameters])
+        end
+      end
+
+      def sourced(registry, layers)
+        index = registry.respond_to?(:index) ? registry.index : nil
+        return [] unless index&.deferrable && registry.offered(index.call_name, layers: layers)
+
+        index.deferrable.call.map do |tool|
+          Deferred.new(name: tool.acts_as, description: tool.description, schema: tool.schema)
+        end
+      end
+
+      private_class_method :builtins, :sourced
+    end
+  end
+end

data/lib/samagotchi/tools/registry.rb

@@ -41,8 +41,13 @@ 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 +sourced+ whether a source (an MCP server's bundle)
-      # registered when the plugins loaded.
-      Index = Data.define(:source, :call_name, :sourced)
+      # registered when the plugins loaded. +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, :sourced, :deferrable, :wrap) do
+        def initialize(source:, call_name:, sourced:, deferrable: nil, wrap: nil) = super
+      end
 
       def initialize
         @entries = {}

data/lib/samagotchi/tools/tool_index.rb

@@ -56,6 +56,8 @@ module Samagotchi
         group: { type: "string", description: "search only this group" }
       }.freeze
       CALL_DESCRIPTION = "Call a tool #{FIND_NAME} found.".freeze
+      # A keyword answer's first line.
+      CALL_HINT = "Call one with #{CALL_NAME}(tool: \"<group>/<tool>\", args: {…}).".freeze
       CALL_PARAMS = {
         tool: { type: "string", required: true, description: "the tool as <group>/<tool>" },
         args: { type: "object", description: "the arguments, per the inputSchema #{FIND_NAME} gave" }
@@ -84,6 +86,19 @@ module Samagotchi
       # A Group's states.
       STATES = %i[ready starting failed].freeze
 
+      # A search's answer (#find): its text, and the tools it loads on a host
+      # that loads tools (+loaded+: the wire names of a keyword answer's
+      # callable matches, the ones a request can declare deferred; none for
+      # an empty query, a miss or the names listing).
+      class FoundText < String
+        attr_reader :loaded
+
+        def initialize(text, loaded = [])
+          super(text)
+          @loaded = loaded.freeze
+        end
+      end
+
       # One group of a source's tools (an MCP server): +summary+ its line in
       # the search tool's description (nil: its name and tool count only),
       # +state+ :ready, :starting (its tools may come: a lookup waits) or
@@ -236,7 +251,8 @@ module Samagotchi
           registry.register(spec.name, source: SOURCE, unwrap: unwrap, **spec.entry_fields(nil))
           spec
         end
-        registry.index = Registry::Index.new(source: SOURCE, call_name: CALL_NAME, sourced: !@sources.empty?)
+        registry.index = Registry::Index.new(source: SOURCE, call_name: CALL_NAME, sourced: !@sources.empty?,
+                                             deferrable: -> { deferrable }, wrap: ->(call) { wrap(call) })
         declared!(declared)
         declared.map(&:name)
       end
@@ -286,11 +302,12 @@ module Samagotchi
       # empty query every group's tool names. +server+ is the parameter's
       # name before it was +group+: a model that still gives it is told
       # every group was searched.
+      # @return [FoundText]
       def find(query, only = nil, server: nil)
         answer = find_in(query, only)
         return answer unless (only.nil? || only.strip.empty?) && !server.to_s.strip.empty?
 
-        "(searched every group)\n#{answer}"
+        FoundText.new("(searched every group)\n#{answer}", answer.loaded)
       end
 
       # ── The call ────────────────────────────────────────────────────────
@@ -348,6 +365,56 @@ module Samagotchi
         inner && BuiltinCalls.build(entry.name, inner).merge(via: CALL_NAME)
       end
 
+      # The sources' tools a host that loads tools may declare deferred
+      # (Tools::DeferredTools), by their acts_as: callable (no refusal),
+      # the only tool with that acts_as, a name Messages takes, and no
+      # registered tool's. Sorted by acts_as, so the same index gives the
+      # same list in any session and after a respawn.
+      # @return [Array<Tool>]
+      def deferrable
+        tools = groups.reject { |group| own?(group) }.flat_map(&:tools)
+        counts = tools.map(&:acts_as).tally
+        tools.select do |tool|
+          tool.refusal.nil? && counts[tool.acts_as] == 1 && tool.acts_as.match?(DEFERRABLE_NAME) &&
+            !@registry&.key?(tool.acts_as)
+        end.sort_by(&:acts_as)
+      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
+      # <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]
+      def deferred_name(name)
+        name = name.to_s.strip
+        bare = name.delete_prefix("#{CHI_GROUP}/")
+        return bare if @registry&.indexed(bare)
+
+        tool = lookup_quietly(name) or return nil
+        return nil if tool.entry || tool.refusal
+
+        deferrable.any? { |t| t.acts_as == tool.acts_as } ? tool.acts_as : nil
+      end
+
+      # What a deferred source tool's wire name may be (Messages' tool
+      # name rule).
+      DEFERRABLE_NAME = /\A[a-zA-Z0-9_-]{1,128}\z/
+
+      # A direct call of a deferrable tool (#deferrable) by its acts_as, as
+      # the call_tool call it runs as (ToolRunner#run, under a host that
+      # loads tools): the call tool's row, rules and approvals. Nil for any
+      # other call.
+      # @return [Hash, nil]
+      def wrap(call)
+        name = call[:name].to_s
+        return nil if name.empty? || @registry&.key?(name)
+
+        tool = deferrable.find { |t| t.acts_as == name } or return nil
+        args = call[:args].is_a?(Hash) ? call[:args] : {}
+        BuiltinCalls.build(CALL_NAME, { "tool" => tool.full_name, "args" => args })
+      end
+
       # The call tool's activity row: <group>/<tool> and its arguments.
       def call_preview(args)
         tool = lookup_quietly(args["tool"].to_s)
@@ -403,17 +470,32 @@ module Samagotchi
         searched = all
         if only && !only.strip.empty?
           searched = all.select { |group| group.name == only.strip }
-          return "Error: no group #{only.strip}. Groups: #{all.map(&:name).join(", ")}" if searched.empty?
+          return FoundText.new("Error: no group #{only.strip}. Groups: #{all.map(&:name).join(", ")}") if searched.empty?
         end
-        return names_text(searched) if words(query).empty?
+        return FoundText.new(names_text(searched)) if words(query).empty?
 
         matches = ranked(query, searched.flat_map(&:tools)).take(FIND_RESULTS)
-        return "No tool matches \"#{query.strip}\".\n\n#{names_text(searched)}" if matches.empty?
+        return FoundText.new("No tool matches \"#{query.strip}\".\n\n#{names_text(searched)}") if matches.empty?
 
         blocks = matches.map { |tool| match_text(tool, all) }
         unsearched = searched.filter_map { |group| "#{group.name} #{group.note}" if group.tools.empty? && group.note }
         blocks << "Not searched: #{unsearched.join("; ")}." unless unsearched.empty?
-        "Call one with #{CALL_NAME}(tool: \"<group>/<tool>\", args: {…}).\n\n#{blocks.join("\n\n")}"
+        FoundText.new("#{CALL_HINT}\n\n#{blocks.join("\n\n")}",
+                      loadable(matches))
+      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
+      # its acts_as when it is #deferrable.
+      def loadable(matches)
+        sourced = nil
+        matches.filter_map do |tool|
+          next tool.name if tool.entry
+          next if tool.refusal
+
+          sourced ||= deferrable.map(&:acts_as)
+          tool.acts_as if sourced.include?(tool.acts_as)
+        end
       end
 
       # What the sources hear of the declared tools (/mcp's last line).

data/lib/samagotchi/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.98.0
+  version: 0.99.0
 platform: ruby
 authors:
 - Dmitry Dedov
@@ -590,6 +590,7 @@ files:
 - lib/samagotchi/tool_call_parser.rb
 - lib/samagotchi/tool_declarations.rb
 - lib/samagotchi/tool_ids.rb
+- lib/samagotchi/tool_loads.rb
 - lib/samagotchi/tool_output_cut.rb
 - lib/samagotchi/tool_output_files.rb
 - lib/samagotchi/tool_response.rb
@@ -605,6 +606,7 @@ files:
 - lib/samagotchi/tools/builtins.rb
 - lib/samagotchi/tools/cancel_reminder.rb
 - lib/samagotchi/tools/context_read.rb
+- lib/samagotchi/tools/deferred_tools.rb
 - lib/samagotchi/tools/delegate.rb
 - lib/samagotchi/tools/delegate_cursor.rb
 - lib/samagotchi/tools/delegate_relay.rb