samagotchi 0.67.0 → 0.69.0

data/lib/samagotchi/toolkit_command.rb

@@ -7,7 +7,8 @@ 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
+  # toolkit and the tools it leaves out (the ones find_tools reaches, the
+  # ones it removes); `/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
@@ -57,7 +58,9 @@ module Samagotchi
       [[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.
+    # The toolkit, its declared tools with tokens, and the ones left out:
+    # reachable with find_tools / call_tool, removed (only /toolkit add
+    # brings one back), or, with call_tool not declared, not loaded.
     def listing(explained)
       toolkit = explained.toolkit
       lines = ["toolkit: #{toolkit.label}#{" (applies at the next turn's start)" if explained.pending}"]
@@ -68,7 +71,13 @@ module Samagotchi
       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(", ")}"
+      if explained.reachable.empty?
+        lines << "  not loaded: #{left_out.empty? ? "none" : left_out.join(", ")}"
+      else
+        route = explained.removed.include?("find_tools") ? "call_tool" : "find_tools"
+        lines << "  reachable (#{route}): #{explained.reachable.join(", ")}"
+        lines << "  removed: #{explained.removed.empty? ? "none" : explained.removed.join(", ")}"
+      end
       lines << "  toolkits: #{@engine.toolkit_kits.keys.join(", ")}; #{USAGE.delete_prefix("usage: ")} changes it"
       lines.join("\n")
     end
@@ -101,8 +110,15 @@ module Samagotchi
       added = names(after) - names(before)
       removed = names(before) - names(after)
       parts = []
+      # Removed (hard: call_tool can't reach it), declared before or not;
+      # left out by the kit (soft); reachable now and not before.
+      hard = after.removed - before.removed
+      left = removed - hard
+      soft = after.reachable - before.reachable - removed
       parts << "declares #{added.join(", ")}" unless added.empty?
-      parts << "leaves out #{removed.join(", ")}" unless removed.empty?
+      parts << "leaves out #{left.join(", ")}" unless left.empty?
+      parts << "removes #{hard.join(", ")} (call_tool can't reach #{hard.size == 1 ? "it" : "them"})" unless hard.empty?
+      parts << "lets call_tool reach #{soft.join(", ")}" unless soft.empty?
       parts << "declares the same tools under its own name" if parts.empty?
       "Switching to #{after.toolkit.label} #{parts.join("; ")}."
     end

data/lib/samagotchi/tools/builtin_calls.rb

@@ -63,6 +63,14 @@ module Samagotchi
       # called_as: with the model's own spelling.
       ALIASES = { "bash" => "execute" }.freeze
 
+      # The tool index's call tool, whose call of a built-in runs as that
+      # built-in (ToolIndex#unwrap; ToolIndex::CALL_NAME is this), and the
+      # group it names them by. The one place the name is spelled.
+      VIA = "call_tool"
+      VIA_GROUP = "chi/"
+      # A saved run's "[name]" lead (ToolResponse::LEAD).
+      SAVED_LEAD = /\A\[([^\]\s]+)\]/
+
       # One built-in's mapping, resolved from its schema and OVERRIDES.
       Row = Data.define(:name, :content_keys, :path_key, :fields, :aliases, :verbatim, :fallback, :fallback_key,
                         :options) do
@@ -97,7 +105,11 @@ module Samagotchi
         unknown = ([path_key].compact + Array(o[:verbatim]) + Array(o[:also]) + o.fetch(:aliases, {}).keys) - properties
         unknown << content_keys.join("/") unless content_keys.empty? || content_keys.intersect?(properties)
         raise ArgumentError, "#{name}: overrides name no schema property: #{unknown.join(", ")}" unless unknown.empty?
-        raise ArgumentError, "#{name}: a property would replace the call's name" if fields.include?("name")
+        # A property can't set the call's name, nor the fields only chi sets
+        # (an alias's called_as, an unwrapped call's via).
+        if (reserved = fields & %w[name called_as via]).any?
+          raise ArgumentError, "#{name}: a property would replace the call's #{reserved.first}"
+        end
 
         Row.new(name: name, content_keys: content_keys, path_key: path_key, fields: fields,
                 aliases: o.fetch(:aliases, {}), verbatim: Array(o[:verbatim]), fallback: o[:fallback],
@@ -135,6 +147,38 @@ module Samagotchi
         call
       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]").
+      # @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)
+
+        build(name, saved_args(call[:args]["args"])).merge(via: VIA)
+      end
+
+      def ran_as?(output, name)
+        lead = output[SAVED_LEAD, 1]
+        lead ? lead == name : output.start_with?("Error: #{name} ")
+      end
+
+      # call_tool's inner args as saved: an object, or its JSON text.
+      def saved_args(args)
+        args = JSON.parse(args) if args.is_a?(String) && !args.strip.empty?
+        args.is_a?(Hash) ? args : {}
+      rescue JSON::ParserError
+        {}
+      end
+
       # An execute-shaped call the model spelled +name+: built as its +target+,
       # tagged with the model's spelling for the activity event and the log.
       def aliased(name, target, args, raw)

data/lib/samagotchi/tools/registry.rb

@@ -26,18 +26,33 @@ module Samagotchi
       # @!attribute layer [Symbol, nil] the LLM context layer the tool
       #   belongs to (LLMContextStrategy): offered only in a turn running
       #   under it (forget_outputs, :forget); nil: always
-      Entry = Struct.new(:name, :schema, :handler, :label, :preview, :targets, :refs, :source, :layer, keyword_init: true) do
+      # @!attribute unwrap [#call, nil] (call, layers) → the call it stands
+      #   for, run in its place before the guardrail gate (call_tool on one
+      #   of chi's own tools: Tools::ToolIndex#unwrap), or nil to run it as
+      #   it is; nil on every other tool
+      Entry = Struct.new(:name, :schema, :handler, :label, :preview, :targets, :refs, :source, :layer, :unwrap,
+                         keyword_init: true) do
         def core? = source == "core"
 
         # Offered in a turn under +layers+ (the turn's LLM context layers).
         def offered?(layers) = layer.nil? || Array(layers).include?(layer)
       end
 
+      # 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)
+
       def initialize
         @entries = {}
         @toolkit = nil
+        @index = nil
       end
 
+      # The tool index's declaration (Index), nil without one.
+      attr_accessor :index
+
       # 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
@@ -45,11 +60,12 @@ module Samagotchi
       attr_accessor :toolkit
 
       # @return [Entry]
-      def register(name, schema:, handler:, label: nil, preview: nil, targets: nil, refs: nil, source: "core", layer: nil)
+      def register(name, schema:, handler:, label: nil, preview: nil, targets: nil, refs: nil, source: "core", layer: nil,
+                   unwrap: nil)
         raise ArgumentError, "tool #{name} is already registered" if @entries.key?(name)
 
         @entries[name] = Entry.new(name: name, schema: schema, handler: handler, label: label, preview: preview,
-                                   targets: targets, refs: refs, source: source, layer: layer)
+                                   targets: targets, refs: refs, source: source, layer: layer, unwrap: unwrap)
       end
 
       # Remove a tool (a plugin's tool set changed after load).
@@ -70,18 +86,48 @@ module Samagotchi
       end
 
       # The entry +name+ names when the session's toolkit leaves it out (a
-      # real tool the model can't call here), nil otherwise.
+      # real tool the model can't call here, by its name), nil otherwise.
       # @return [Entry, nil]
       def left_out(name, layers: [])
         entry = self[name]
-        entry if entry&.offered?(layers) && !declared?(entry)
+        entry if entry && left_out?(entry, layers, @toolkit)
       end
 
       # The tools +toolkit+ (the session's by default) leaves out of a turn
-      # under +layers+.
+      # under +layers+. The tool index's own aren't, unless it removes them:
+      # they are declared when there is something to reach.
       # @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)
+        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).
+      # @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.
+      # @return [Array<String>] in declaration order
+      def reachable_names(layers: [], toolkit: @toolkit)
+        return [] unless call_offered?(toolkit)
+
+        ordered(@entries.values.select { |entry| soft?(entry, layers, toolkit) }).map(&:name)
+      end
+
+      # The tools +toolkit+ removes from a turn under +layers+ (remove:,
+      # --no-tool, /toolkit remove): only the user brings them back.
+      # @return [Array<String>] in declaration order
+      def removed_names(layers: [], toolkit: @toolkit)
+        return [] if toolkit.nil?
+
+        ordered(@entries.values.select { |entry| entry.offered?(layers) && toolkit.removed.include?(entry.name) })
+          .map(&:name)
       end
 
       # Every tool +source+ registered, declared or not (a plugin's tool set
@@ -112,7 +158,48 @@ module Samagotchi
 
       private
 
-      def declared?(entry, toolkit = @toolkit) = toolkit.nil? || toolkit.declares?(entry)
+      # 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
+      # doesn't remove (#index_needed?); unless it removes them.
+      def declared?(entry, toolkit = @toolkit)
+        if index_entry?(entry)
+          !toolkit&.removed&.include?(entry.name) && index_needed?(toolkit)
+        else
+          toolkit.nil? || toolkit.declares?(entry)
+        end
+      end
+
+      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
+      # left out counts only while call_tool can reach it (not removed).
+      def index_needed?(toolkit)
+        return true if @index.sourced
+        return false if toolkit&.removed&.include?(@index.call_name)
+
+        @entries.each_value.any? { |entry| soft?(entry, [], toolkit) }
+      end
+
+      def left_out?(entry, layers, toolkit)
+        return false unless entry.offered?(layers) && !declared?(entry, toolkit)
+
+        !index_entry?(entry) || toolkit&.removed&.include?(entry.name) == true
+      end
+
+      # A built-in +toolkit+ leaves out of a turn under +layers+ without
+      # removing it.
+      def soft?(entry, layers, toolkit)
+        !toolkit.nil? && entry.core? && entry.offered?(layers) && !toolkit.removed.include?(entry.name) &&
+          !toolkit.declares?(entry)
+      end
+
+      # Whether +toolkit+ declares the index's call tool.
+      def call_offered?(toolkit)
+        entry = @index && self[@index.call_name]
+        !entry.nil? && declared?(entry, toolkit)
+      end
 
       def ordered(entries)
         core, added = entries.partition(&:core?)