samagotchi 0.154.1 → 0.156.0

data/lib/samagotchi/tools/tool_index.rb

@@ -3,6 +3,7 @@
 require "json"
 require_relative "args"
 require_relative "builtin_calls"
+require_relative "index_hint"
 require_relative "registry"
 require_relative "../log"
 require_relative "../token_usage"
@@ -11,6 +12,10 @@ require_relative "../plugin/tool_spec"
 
 module Samagotchi
   module Tools
+    # Read only when a surface is built (#declare, #refresh!): the bundle
+    # test kit loads this file for ToolIndex.new and never builds one.
+    autoload :ToolSurface, File.expand_path("tool_surface", __dir__)
+
     # The tools a session knows but doesn't declare one by one, and the two
     # tools that reach them (docs/plugins.md, "Publishing tools to the
     # index"): find_tools, a keyword search that answers each match's
@@ -18,11 +23,20 @@ module Samagotchi
     # 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 tools the session's toolkit leaves out but doesn't remove, chi's
-    # built-ins and its bundles' (chi.tool) alike (Registry#reachable_names),
+    # built-ins and its bundles' (chi.tool) alike (ToolSurface#index_only),
     # 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.
     #
+    # What it reads of the session's tools is a ToolSurface, always given:
+    # the turn's (TurnContext#surface) on the turn's path (the two tools'
+    # handlers, through their ToolContext; call_tool's row and targets,
+    # from the row and the gate; #unwrap, #wrap, #deferrable and
+    # #unreached_tool, from the runner and the deferred list); one built
+    # from the Registry #declare registered in at load and at #refresh!;
+    # ToolkitBinding#published's for ctx.load_tools (#deferred_name). None
+    # where one is needed raises MissingSurface.
+    #
     # 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 tool reachable. The search tool's
@@ -58,8 +72,6 @@ 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" }
@@ -70,10 +82,11 @@ module Samagotchi
       class ToolkitGroupRefusal < StandardError
         RULE = "toolkit-group"
 
-        # The refusal of +tool+ under +registry+'s toolkit, naming a kit that
-        # reaches its group when the registry can tell (Registry#reaching_kit).
-        def self.for(tool, registry)
-          new(tool, registry.toolkit, kit: registry.respond_to?(:reaching_kit) ? registry.reaching_kit&.call(tool.group) : nil)
+        # The refusal of +tool+ under +surface+'s toolkit (a ToolSurface),
+        # naming a kit that reaches its group when it can tell
+        # (ToolSurface#reaching_kit).
+        def self.for(tool, surface)
+          new(tool, surface.toolkit, kit: surface.reaching_kit&.call(tool.group))
         end
 
         def initialize(tool, toolkit, kit: nil)
@@ -248,12 +261,12 @@ module Samagotchi
       # @return [Array<Source>] the sources added, in order
       def sources = @sources.dup
 
-      # Every group, now: the index's own (#registry_groups), then the
-      # sources'. A source group with a reserved name, or one an earlier
-      # group has, is left out of search, lookup and the description (said
-      # once per name: a source publishes after load too).
-      def all_groups
-        own = registry_groups
+      # Every group, now: the index's own (#registry_groups, from
+      # +surface+), then the sources'. A source group with a reserved name,
+      # or one an earlier group has, is left out of search, lookup and the
+      # description (said once per name: a source publishes after load too).
+      def all_groups(surface)
+        own = registry_groups(surface)
         taken = own.map(&:name) | RESERVED_GROUPS
         kept = @sources.flat_map(&:groups).select do |group|
           why = if RESERVED_GROUPS.include?(group.name) then "reserved"
@@ -266,9 +279,11 @@ module Samagotchi
         own + kept
       end
 
-      def reached_groups
-        groups = all_groups
-        toolkit = @registry&.toolkit
+      # The groups +surface+'s toolkit reaches (#all_groups' own, and the
+      # source groups #declare found that it reaches).
+      def reached_groups(surface)
+        groups = all_groups(surface)
+        toolkit = surface.toolkit
         return groups if toolkit.nil? || toolkit.groups == :all
 
         declared = @declared_group_names || groups.reject { |group| own?(group) }.map(&:name)
@@ -285,10 +300,11 @@ module Samagotchi
       # @return [Array<String>] the names registered
       def declare(registry, failures: nil)
         @registry = registry
-        @described = description_lines(all_groups.reject { |group| own?(group) }).freeze
+        at_load = ToolSurface.for(registry)
+        @described = description_lines(all_groups(at_load).reject { |group| own?(group) }).freeze
         @declared_group_names = @described.keys.freeze
         loaded = registry.registered
-        specs = [find_spec, call_spec]
+        specs = [find_spec(at_load), call_spec]
         declared = specs.filter_map do |spec|
           if (taken = registry[spec.name])
             failures&.add("tool #{spec.name}", "already registered (#{taken.source}); the tool index's is left out",
@@ -296,14 +312,17 @@ module Samagotchi
             next
           end
 
-          unwrap = (->(call, layers) { unwrap(call, layers) } if spec.name == CALL_NAME)
-          registry.register(spec.name, source: SOURCE, unwrap: unwrap, **spec.entry_fields(nil))
+          unwrap = (->(call, surface) { unwrap(call, surface) } if spec.name == CALL_NAME)
+          registry.register(spec.name, source: SOURCE, unwrap: unwrap,
+                                       **spec.entry_fields(nil).merge(own_fields(spec)))
           spec
         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) }, loaded: loaded)
-        declared!(declared)
+                                             deferrable: ->(surface) { deferrable(surface) },
+                                             wrap: ->(call, surface) { wrap(call, surface) },
+                                             unreached: ->(name, surface) { unreached_tool(name, surface) },
+                                             loaded: loaded)
+        declared!(declared, ToolSurface.for(registry))
         declared.map(&:name)
       end
 
@@ -314,8 +333,9 @@ module Samagotchi
         entry = @registry && @registry[FIND_NAME]
         return unless entry&.source == SOURCE
 
-        entry.schema = entry.schema.merge(description: find_description)
-        declared!([find_spec, call_spec].select { |spec| @registry[spec.name]&.source == SOURCE })
+        surface = ToolSurface.for(@registry)
+        entry.schema = entry.schema.merge(description: find_description(surface))
+        declared!([find_spec(surface), call_spec].select { |spec| @registry[spec.name]&.source == SOURCE }, surface)
       end
 
       # A checked tool declaration's (Plugin::ToolSpec) definition as
@@ -340,10 +360,10 @@ module Samagotchi
       # server's: its name, and its summary if it has one). Never every
       # tool: knowing the names, a model searches less and guesses
       # arguments.
-      def find_description
+      def find_description(surface)
         "Search tools this session doesn't declare, by keywords. It answers up to #{FIND_RESULTS} tools, each with " \
           "its name (<group>/<tool>) and inputSchema; call one with #{CALL_NAME}. An empty query lists every tool's " \
-          "name.\nGroups:\n#{(description_lines(registry_groups).values + described_groups.values).join("\n")}"
+          "name.\nGroups:\n#{(description_lines(registry_groups(surface)).values + described_groups(surface).values).join("\n")}"
       end
 
       # ── Search ──────────────────────────────────────────────────────────
@@ -351,10 +371,10 @@ module Samagotchi
       # The search tool: the best matches with their schemas, or with an
       # 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.
+      # every group was searched. +surface+: the turn's (the handler's).
       # @return [FoundText]
-      def find(query, only = nil, server: nil)
-        answer = find_in(query, only)
+      def find(query, only = nil, surface:, server: nil)
+        answer = find_in(query, only, surface)
         return answer unless (only.nil? || only.strip.empty?) && !server.to_s.strip.empty?
 
         FoundText.new("(searched every group)\n#{answer}", answer.loaded)
@@ -366,11 +386,12 @@ module Samagotchi
       # 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 chi tool runs as itself, #unwrap, or not at all).
-      def call(name, args)
-        tool = lookup(name)
+      # +surface+: the turn's (the handler's).
+      def call(name, args, surface:)
+        tool = lookup(name, surface)
         return tool if tool.is_a?(String)
 
-        unless claimed(name.strip)&.first == tool.acts_as
+        unless claimed(name.strip, surface)&.first == tool.acts_as
           # A bare acts_as of a source with no prefix: guardrails can't
           # name it before its tool is listed (#claimed), so only
           # <group>/<tool> is taken.
@@ -399,16 +420,16 @@ module Samagotchi
       # 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
+      # turn's +surface+ doesn't declare call_tool, for an MCP tool, a miss
       # or arguments that aren't an object.
       # @return [Hash, nil]
-      def unwrap(call, layers = [])
-        return nil unless @registry&.offered(CALL_NAME, layers: layers)
+      def unwrap(call, surface)
+        return nil unless surface.declared_entry(CALL_NAME)
 
         args = call[:args].is_a?(Hash) ? call[:args] : {}
         name = args["tool"].to_s.strip
-        tool = lookup_quietly(name)
-        entry = tool&.entry || builtin_named(name)
+        tool = lookup_quietly(name, surface)
+        entry = tool&.entry || builtin_named(name, surface)
         return nil unless entry
 
         inner = inner_args(args["args"], tool)
@@ -421,13 +442,13 @@ module Samagotchi
       # 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
-        all = all_groups.reject { |group| own?(group) }.flat_map(&:tools)
-        reached = reached_groups.reject { |group| own?(group) }.flat_map(&:tools)
+      def deferrable(surface)
+        all = all_groups(surface).reject { |group| own?(group) }.flat_map(&:tools)
+        reached = reached_groups(surface).reject { |group| own?(group) }.flat_map(&:tools)
         counts = all.map(&:acts_as).tally
         reached.select do |tool|
           tool.refusal.nil? && counts[tool.acts_as] == 1 && tool.acts_as.match?(DEFERRABLE_NAME) &&
-            !@registry&.key?(tool.acts_as)
+            !surface.registered?(tool.acts_as)
         end.sort_by(&:acts_as)
       end
 
@@ -437,29 +458,29 @@ module Samagotchi
       # <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)
+      def deferred_name(name, surface)
         name = name.to_s.strip
         bare = name.delete_prefix("#{CHI_GROUP}/")
-        return bare if @registry&.indexed(bare)
+        return bare if surface.indexed_entry(bare)
 
-        tool = lookup_quietly(name) or return nil
+        tool = lookup_quietly(name, surface) or return nil
         return nil if tool.entry || tool.refusal
 
-        deferrable.any? { |t| t.acts_as == tool.acts_as } ? tool.acts_as : nil
+        deferrable(surface).any? { |t| t.acts_as == tool.acts_as } ? tool.acts_as : nil
       end
 
       # Finds a source tool regardless of the active toolkit, without
       # waiting for a starting group. Used only to refuse a call or explain
       # a deferred stub for a group the session cannot reach.
-      def unreached_tool(name)
+      def unreached_tool(name, surface)
         name = name.to_s.strip
         return nil if name.empty?
 
-        groups = all_groups.reject { |group| own?(group) }
+        groups = all_groups(surface).reject { |group| own?(group) }
         groups.select! { |group| @declared_group_names.include?(group.name) } if @declared_group_names
         tool = tool_in(name, groups)
         return nil unless tool
-        return nil if reached_groups.any? { |group| group.name == tool.group }
+        return nil if reached_groups(surface).any? { |group| group.name == tool.group }
 
         tool
       end
@@ -473,18 +494,19 @@ module Samagotchi
       # loads tools): the call tool's row, rules and approvals. Nil for any
       # other call.
       # @return [Hash, nil]
-      def wrap(call)
+      def wrap(call, surface)
         name = call[:name].to_s
-        return nil if name.empty? || @registry&.key?(name)
+        return nil if name.empty? || surface.registered?(name)
 
-        tool = deferrable.find { |t| t.acts_as == name } or return nil
+        tool = deferrable(surface).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)
+      # The call tool's activity row: <group>/<tool> and its arguments, as
+      # +surface+ (the turn's) reaches it.
+      def call_preview(args, surface)
+        tool = lookup_quietly(args["tool"].to_s, surface)
         name = tool ? tool.full_name : args["tool"].to_s.strip
         inner = tool && inner_args(args["args"], tool)
         inner ? [name, preview(inner)].reject(&:empty?).join(" ") : name
@@ -495,11 +517,11 @@ module Samagotchi
       # indexed yet (its server still starting) is named from what the
       # model gave (#claimed), so a rule on it fires before the call waits
       # for the server. Nothing for a name that can't be a tool (the call
-      # refuses it).
-      def call_targets(args)
+      # refuses it). +surface+: the turn's (the gate's).
+      def call_targets(args, surface)
         name = args["tool"].to_s.strip
-        tool = lookup_quietly(name)
-        acts_as, label = tool ? [tool.acts_as, "#{tool.group}: #{tool.name}"] : claimed(name)
+        tool = lookup_quietly(name, surface)
+        acts_as, label = tool ? [tool.acts_as, "#{tool.group}: #{tool.name}"] : claimed(name, surface)
         return {} unless acts_as
 
         { acts_as: acts_as, args: inner_args(args["args"], tool) || {}, label: label }.compact
@@ -507,20 +529,41 @@ module Samagotchi
 
       private
 
-      def find_spec
-        Plugin::ToolSpec.build(FIND_NAME, find_description, params: FIND_PARAMS,
+      # The fields +spec+'s tool registers with beside its entry_fields: a
+      # handler whose block is given the call's typed args and the turn's
+      # surface (its ToolContext's), and call_tool's preview and targets,
+      # given the turn's surface by the row and the gate
+      # (Registry::Entry#preview_of / #targets_of). Without a surface each
+      # raises MissingSurface: none reads the Registry as it is now.
+      def own_fields(spec)
+        parameters = spec.schema[:parameters]
+        args = ->(call) { Plugin::ToolSpec.args_of(call, parameters) }
+        fields = { handler: lambda { |call, kctx|
+          Plugin::ToolSpec.result_text(spec.block.call(args.call(call), kctx&.surface || raise(MissingSurface)))
+        } }
+        return fields unless spec.name == CALL_NAME
+
+        fields.merge(preview: ->(call, surface = nil) { call_preview(args.call(call), surface || raise(MissingSurface)) },
+                     targets: ->(call, surface = nil) { call_targets(args.call(call), surface || raise(MissingSurface)) })
+      end
+
+      # The search tool's declaration, its description read from +surface+
+      # (the Registry's now: #declare, #refresh!); its block searches the
+      # turn's (own_fields' handler gives it).
+      def find_spec(surface)
+        Plugin::ToolSpec.build(FIND_NAME, find_description(surface), params: FIND_PARAMS,
                                                            preview: lambda { |args|
                                                              [args["query"].to_s.strip, args["group"] && "in #{args["group"]}"].compact.join(" ")
-                                                           }) do |args, _ctx|
-          find(args["query"].to_s, args["group"], server: args["server"])
+                                                           }) do |args, turn|
+          find(args["query"].to_s, args["group"], server: args["server"], surface: turn)
         end
       end
 
+      # The call tool's declaration; its preview and targets are own_fields'.
       def call_spec
-        Plugin::ToolSpec.build(CALL_NAME, CALL_DESCRIPTION, params: CALL_PARAMS, label: @sources.first&.label,
-                                                           preview: ->(args) { call_preview(args) },
-                                                           targets: ->(args) { call_targets(args) }) do |args, _ctx|
-          call(args["tool"].to_s, args["args"])
+        Plugin::ToolSpec.build(CALL_NAME, CALL_DESCRIPTION, params: CALL_PARAMS,
+                                                           label: @sources.first&.label) do |args, turn|
+          call(args["tool"].to_s, args["args"], surface: turn)
         end
       end
 
@@ -532,8 +575,8 @@ module Samagotchi
         @sources.find { |source| source.groups.any? { |g| g.name == group } }
       end
 
-      def find_in(query, only)
-        all = reached_groups
+      def find_in(query, only, surface)
+        all = reached_groups(surface)
         searched = all
         if only && !only.strip.empty?
           searched = all.select { |group| group.name == only.strip }
@@ -547,62 +590,63 @@ module Samagotchi
         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?
-        FoundText.new("#{CALL_HINT}\n\n#{blocks.join("\n\n")}",
-                      loadable(matches))
+        FoundText.new("#{IndexHint::CALL_HINT}\n\n#{blocks.join("\n\n")}",
+                      loadable(matches, surface))
       end
 
       # The wire names of +matches+ a request can declare deferred: a
       # 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)
+      def loadable(matches, surface)
         sourced = nil
         matches.filter_map do |tool|
           next tool.name if tool.entry
           next if tool.refusal
 
-          sourced ||= deferrable.map(&:acts_as)
+          sourced ||= deferrable(surface).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).
-      def declared!(specs)
+      # What the sources hear of the declared tools (/mcp's last line), the
+      # groups +surface+ (the Registry's now) reaches.
+      def declared!(specs, surface)
         names = specs.map(&:name)
         tokens = specs.sum { |spec| ToolIndex.spec_tokens(spec) }
-        groups = reached_groups.reject { |group| own?(group) }.map(&:name)
+        groups = reached_groups(surface).reject { |group| own?(group) }.map(&:name)
         @sources.each { |source| source.declared!(names, tokens, groups) }
       end
 
-      def described_groups
-        return @described unless @registry&.toolkit && @registry.toolkit.groups != :all
+      def described_groups(surface)
+        toolkit = surface.toolkit
+        return @described unless toolkit && toolkit.groups != :all
 
-        @described.select { |name, _line| @registry.toolkit.reaches_group?(name) }
+        @described.select { |name, _line| toolkit.reaches_group?(name) }
       end
 
       def own?(group) = RESERVED_GROUPS.include?(group.name)
 
       # 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)
+      def builtin_named(name, surface)
         return nil unless name.start_with?("#{CHI_GROUP}/")
 
-        entry = @registry[name.delete_prefix("#{CHI_GROUP}/")]
+        entry = surface.registered[name.delete_prefix("#{CHI_GROUP}/")]
         entry unless entry.nil? || entry.source == SOURCE
       end
 
       # 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.
+      # +surface+'s toolkit leaves out but reaches (ToolSurface#index_only;
+      # 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>]
-      def registry_groups
-        names = @registry ? @registry.reachable_names : []
-        return [] if names.empty?
+      def registry_groups(surface)
+        entries = surface.index_only
+        return [] if entries.empty?
 
-        tools = names.map do |name|
-          entry = @registry[name]
+        tools = entries.map do |entry|
           schema = ToolDeclarations.chat_schemas([entry.schema]).first
-          Tool.new(group: CHI_GROUP, name: name, acts_as: name, description: schema[:description].to_s,
+          Tool.new(group: CHI_GROUP, name: entry.name, acts_as: entry.name, description: schema[:description].to_s,
                    schema: JSON.parse(JSON.generate(schema[:parameters])), entry: entry)
         end
         [Group.new(name: CHI_GROUP, summary: CHI_SUMMARY, tools: tools)]
@@ -687,9 +731,9 @@ module Samagotchi
       # miss is the error text: a failed group's error, else the closest
       # tools.
       # @return [Tool, String]
-      def lookup(name, waited: false)
+      def lookup(name, surface, waited: false)
         name = name.strip
-        all = reached_groups
+        all = reached_groups(surface)
         tool = all.lazy.filter_map do |group|
           next unless name.start_with?("#{group.name}/")
 
@@ -703,17 +747,21 @@ module Samagotchi
         return "Error: #{name} names #{same.map(&:full_name).join(" and ")}; call one as <group>/<tool>" if same.size > 1
 
         # 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
+        # starting server's tool. A layer's tool (forget_outputs) isn't
+        # counted, as before the surface (the Registry was asked without
+        # the turn's layers).
+        declared = surface.declared_entry(name)
+        if declared && declared.source != SOURCE && declared.layer.nil?
+          return "Error: #{name} is declared; call it directly"
+        end
 
         # A name with a group's <group>/ waits for that group only; any
         # other name (an acts_as) for every one starting.
-        named = reached_groups.select { |group| name.start_with?("#{group.name}/") }
-        starting = (named.empty? ? reached_groups : named).select { |group| group.state == :starting }
+        named = reached_groups(surface).select { |group| name.start_with?("#{group.name}/") }
+        starting = (named.empty? ? reached_groups(surface) : named).select { |group| group.state == :starting }
         unless waited || starting.empty?
           starting.each { |group| source_of(group.name)&.wait(group.name) }
-          return lookup(name, waited: true)
+          return lookup(name, surface, waited: true)
         end
 
         failed = all.find { |group| group.state == :failed && name.start_with?("#{group.name}/") }
@@ -726,8 +774,8 @@ module Samagotchi
       end
 
       # #lookup's tool, without waiting for a start: nil on a miss.
-      def lookup_quietly(name)
-        tool = lookup(name, waited: true)
+      def lookup_quietly(name, surface)
+        tool = lookup(name, surface, waited: true)
         tool.is_a?(Tool) ? tool : nil
       end
 
@@ -750,8 +798,8 @@ module Samagotchi
       # bare name with a source's prefix as it is (no label). Nil for
       # anything else.
       # @return [Array(String, String), Array(String, nil), nil]
-      def claimed(name)
-        all = all_groups
+      def claimed(name, surface)
+        all = all_groups(surface)
         if (own = all.select { |g| own?(g) }.find { |g| g.tools.any? { |t| t.acts_as == name } })
           return [name, "#{own.name}: #{name}"]
         end