samagotchi 0.66.0 → 0.67.0

data/lib/samagotchi/plugin/api.rb

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
 
-require "json"
 require_relative "../toolkit"
 require_relative "../log"
 require_relative "../hooks/registry"
-require_relative "../tools/args"
 require_relative "../commands/registry"
 require_relative "service"
 require_relative "tool_result"
+require_relative "tool_spec"
 
 module Samagotchi
   module Plugin
@@ -16,8 +15,6 @@ module Samagotchi
     # #register returns, so a plugin that raises halfway adds nothing.
     class Api
       COMMAND_NAME = %r{\A/[a-z][a-z0-9_-]{0,31}\z}
-      TOOL_NAME = /\A[a-z][a-z0-9_]{0,47}\z/
-      PARAM_NAME = /\A[a-z_][a-z0-9_]*\z/i
       ANNOTATION_LABEL_MAX = 40
       ANNOTATIONS_MAX = 5
 
@@ -38,6 +35,8 @@ module Samagotchi
         @services = []
         @inits = []
         @toolkits = []
+        @peer_sources = []
+        @tool_source = nil
         @committed = false
       end
 
@@ -118,11 +117,11 @@ module Samagotchi
       #   a list of {kind:, target:, label:, actions:} (RowRefs, Ref). Run
       #   once per call on the tool path, so it must be cheap (no I/O)
       def tool(name, description, **, &)
-        spec = Api.tool_spec(name, description, **, &)
-        if (taken = @registries.tools[spec[:name]])
-          raise ArgumentError, "tool #{spec[:name]} is already registered (#{taken.source})"
+        spec = ToolSpec.build(name, description, **, &)
+        if (taken = @registries.tools[spec.name])
+          raise ArgumentError, "tool #{spec.name} is already registered (#{taken.source})"
         end
-        raise ArgumentError, "tool #{spec[:name]} is registered twice" if @tools.any? { |tool| tool[:name] == spec[:name] }
+        raise ArgumentError, "tool #{spec.name} is registered twice" if @tools.any? { |tool| tool.name == spec.name }
 
         @tools << spec
         nil
@@ -146,7 +145,7 @@ module Samagotchi
         yield set
         if (stage = @registries.stage_tools)
           stage.call(@bundle, set.specs, @context)
-        elsif Api.apply_tools(@registries.tools, @bundle, set.specs, @context)[:changed]
+        elsif ToolSpec.apply(@registries.tools, @bundle, set.specs, @context)[:changed]
           tools_changed!
         end
         nil
@@ -154,7 +153,7 @@ module Samagotchi
 
       # What #replace_tools' block declares tools on.
       class ToolSet
-        # @return [Array<Hash>]
+        # @return [Array<ToolSpec>]
         attr_reader :specs
 
         def initialize
@@ -163,8 +162,8 @@ module Samagotchi
 
         # As Api#tool.
         def tool(name, description, **, &)
-          spec = Api.tool_spec(name, description, **, &)
-          raise ArgumentError, "tool #{spec[:name]} is registered twice" if @specs.any? { |s| s[:name] == spec[:name] }
+          spec = ToolSpec.build(name, description, **, &)
+          raise ArgumentError, "tool #{spec.name} is registered twice" if @specs.any? { |s| s.name == spec.name }
 
           @specs << spec
           nil
@@ -250,6 +249,32 @@ module Samagotchi
         nil
       end
 
+      # Publish tools into the session's tool index instead of declaring
+      # them one by one (docs/plugins.md, "Publishing tools to the index"):
+      # the model searches them with find_tools and calls one with
+      # call_tool (<group>/<tool>), which chi declares once, after the
+      # plugins load, when a source registered. Returns the source: its
+      # #publish(groups) (ToolIndex::Group values, each with its
+      # ToolIndex::Tool values) swaps in the plugin's whole list, from any
+      # thread, at any time, and changes only what searches answer.
+      # @param label [String] the call tool's row label (default: the bundle)
+      # @param call [#call] (tool, args, ctx) → the call's result, as a
+      #   tool's block returns it; +tool+ a ToolIndex::Tool the index looked
+      #   up and checked, +args+ typed by its schema
+      # @param acts_as [#call] (group, tool) → the name guardrail rules
+      #   match for a tool from its names alone (one not published yet)
+      # @param wait [#call, nil] (group) waits for a :starting group's start
+      # @param prefix [String, nil] a bare name with it is taken as an
+      #   acts_as as given
+      # @return [Tools::ToolIndex::Source]
+      def tool_source(call:, acts_as:, label: @bundle, wait: nil, prefix: nil)
+        raise ArgumentError, "this chi has no tool index (plugins: false)" unless @registries.tool_index
+        raise ArgumentError, "tool_source is declared twice" if @tool_source
+
+        @tool_source = @registries.tool_index.source(label: label, call: call, acts_as: acts_as, wait: wait,
+                                                     prefix: prefix, context: @context)
+      end
+
       TOOLKIT_NAME = /\A[a-z][a-z0-9_-]{0,31}\z/
 
       # A named toolkit sessions can be put on (/toolkit NAME, chi --toolkit,
@@ -273,11 +298,29 @@ module Samagotchi
         nil
       end
 
+      # A context source that holds a peer agent's answers (the peer
+      # bundles' claude-review, codex-review): +label+ is the peer's name
+      # ("Codex", PeerSources::LABEL), said in chi's own lines. Such a
+      # source, when it is a pushed one of the session's own, wakes on
+      # context.peer_turns rather than the 10-minute window, with the peer
+      # line (docs/context.md, Waking). Declared here, in-process, never by
+      # a source file; gone with the bundle.
+      def peer_source(name, label:)
+        raise ArgumentError, "this chi has no peer sources (plugins: false)" unless @registries.peer_sources
+
+        name = @registries.peer_sources.check!(name, label: label, bundle: @bundle)
+        raise ArgumentError, "peer source #{name} is declared twice" if @peer_sources.any? { |item| item[:name] == name }
+
+        @peer_sources << { name: name, label: label.to_s }
+        nil
+      end
+
       # Register what was staged. Called by Loader after #register. What
       # can only be checked now (an annotation's command) is checked before
       # anything is registered: a raise here leaves the registries as they were.
       def commit!
         check_annotations!
+        @peer_sources.each { |item| @registries.peer_sources.check!(item[:name], label: item[:label], bundle: @bundle) }
         context = @context
         @commands.each do |cmd|
           block = cmd[:block]
@@ -287,7 +330,7 @@ module Samagotchi
             block.call(args, context)
           end
         end
-        @tools.each { |tool| @registries.tools.register(tool[:name], source: @bundle, **Api.entry_fields(tool, context)) }
+        @tools.each { |tool| @registries.tools.register(tool.name, source: @bundle, **tool.entry_fields(context)) }
         @hooks.each do |hook|
           block = hook[:block]
           # Logged only (echo: false): a turn's live region is on screen.
@@ -307,12 +350,15 @@ module Samagotchi
           end
         end
         @registries.toolkits&.concat(@toolkits)
+        @registries.tool_index.add(@tool_source) if @tool_source
+        @peer_sources.each { |item| @registries.peer_sources.declare(item[:name], label: item[:label], bundle: @bundle) }
         @committed = true
       end
 
       # @return [Hash] how many of each it registered (for the log)
       def counts = { commands: @commands.size, annotations: @annotations.size, tools: @tools.size, hooks: @hooks.size,
-                     services: @services.size, inits: @inits.size, toolkits: @toolkits.size }
+                     services: @services.size, inits: @inits.size, toolkits: @toolkits.size,
+                     tool_sources: @tool_source ? 1 : 0, peer_sources: @peer_sources.size }
 
       # Each annotation's command is one #command staged.
       def check_annotations!
@@ -325,147 +371,10 @@ module Samagotchi
       end
       private :check_annotations!
 
-      # A checked tool declaration (#tool's arguments: Api#tool and
-      # ToolSet#tool pass theirs on, so a new keyword is added here).
-      # @return [Hash] {name:, schema:, label:, preview:, targets:, refs:, block:}
-      def self.tool_spec(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, refs: nil,
-                         &block)
-        raise ArgumentError, "tool #{name.inspect} needs a block" unless block
-
-        name = name.to_s
-        raise ArgumentError, "tool name #{name.inspect} must be a-z, 0-9 and _ (at most 48)" unless name.match?(TOOL_NAME)
-        raise ArgumentError, "tool #{name}: preview must respond to #call" if preview && !preview.respond_to?(:call)
-        raise ArgumentError, "tool #{name}: targets must respond to #call" if targets && !targets.respond_to?(:call)
-        raise ArgumentError, "tool #{name}: refs must respond to #call" if refs && !refs.respond_to?(:call)
-
-        parameters = schema ? schema_parameters(name, schema) : params_schema(name, params)
-        { name: name, schema: { name: name, description: description.to_s, parameters: parameters },
-          label: label&.to_s, preview: preview, targets: targets, refs: refs, block: block }
-      end
-
-      # Make +bundle+'s tools in +registry+ the +specs+: its tools not in
-      # them go; a new one, or one whose schema or label changed, is
-      # registered (a changed one again, in its place: Tools::Registry
-      # orders bundle tools by bundle and name); an unchanged one is kept
-      # as it is, but for its block, preview:, targets: and refs:, swapped
-      # in place: none of them reaches the prompt, so not a change (that
-      # would build the prompts again). A name
-      # another source has is left out. Called on the turn thread
-      # (Engine#apply_staged_tools!).
-      # @return [Hash] {changed: Boolean, skipped: [String] (why)}
-      def self.apply_tools(registry, bundle, specs, context)
-        wanted = specs.to_h { |spec| [spec[:name], spec] }
-        changed = false
-        registry.by_source(bundle).each do |entry|
-          if (spec = wanted[entry.name]) && spec[:schema] == entry.schema && spec[:label] == entry.label
-            entry_fields(spec, context).slice(:handler, :preview, :targets, :refs).each { |key, value| entry[key] = value }
-            next
-          end
-
-          registry.unregister(entry.name)
-          changed = true
-        end
-        skipped = []
-        specs.each do |spec|
-          if (taken = registry[spec[:name]])
-            skipped << "tool #{spec[:name]} is already registered (#{taken.source})" unless taken.source == bundle
-            next
-          end
-
-          registry.register(spec[:name], source: bundle, **entry_fields(spec, context))
-          changed = true
-        end
-        { changed: changed, skipped: skipped }
-      end
-
-      # Registry#register's keywords for a tool declaration: its block
-      # wrapped as a handler (typed args, the Context), preview, targets, refs.
-      def self.entry_fields(spec, context)
-        block = spec[:block]
-        parameters = spec[:schema][:parameters]
-        preview = per_call(spec[:preview], parameters)
-        {
-          schema: spec[:schema], label: spec[:label],
-          handler: lambda { |call, _kctx|
-            result = block.call(Api.args_of(call, parameters), context)
-            Api.result_text(result)
-          },
-          preview: preview && ->(call) { preview.call(call)&.to_s },
-          targets: per_call(spec[:targets], parameters),
-          refs: per_call(spec[:refs], parameters)
-        }
-      end
-
-      # A plugin's args → value lambda (+fn+) as call → value: it gets the
-      # call's typed args (Api.args_of), as the tool's block does. nil
-      # without one.
-      def self.per_call(fn, parameters)
-        fn && ->(call) { fn.call(Api.args_of(call, parameters)) }
-      end
-
-      # A tool's result as the model reads it: a String (a ToolResult too,
-      # with its images) as it is, a Hash or Array as JSON (its #to_s is
-      # Hash#inspect, which changes with the Ruby version), else #to_s.
-      def self.result_text(result)
-        case result
-        when String then result
-        when Hash, Array then JSON.generate(result)
-        else result.to_s
-        end
-      rescue JSON::GeneratorError
-        result.to_s
-      end
-
-      # A tool call's arguments as a plugin sees them: the parsers' args:
-      # (a call built without one, in a spec say: the call without its
-      # name), string keys, typed by +parameters+, frozen.
-      def self.args_of(call, parameters = nil)
-        given = call[:args].is_a?(Hash) ? call[:args] : call.reject { |key, _| %i[name args].include?(key) }
-        Tools::Args.coerce(given, parameters).freeze
-      end
-
-      # A JSON Schema with symbol keys (property names included), as
-      # ToolDeclarations::TOOL_SCHEMAS has them.
-      def self.symbolize(value)
-        case value
-        when Hash then value.to_h { |key, item| [key.to_sym, symbolize(item)] }
-        when Array then value.map { |item| symbolize(item) }
-        else value
-        end
-      end
-
-      # The parameters object from params: (name => property spec).
-      def self.params_schema(name, params)
-        raise ArgumentError, "tool #{name}: params must be a Hash" unless params.is_a?(Hash)
-
-        required = []
-        properties = params.each_with_object({}) do |(param, spec), acc|
-          param = param.to_s
-          raise ArgumentError, "tool #{name}: parameter name #{param.inspect} is not a plain word" unless param.match?(PARAM_NAME)
-          raise ArgumentError, "tool #{name}: parameter #{param} must be a Hash {type:, description:}" unless spec.is_a?(Hash)
-
-          spec = Api.symbolize(spec)
-          required << param if spec.delete(:required) == true
-          acc[param.to_sym] = { type: (spec.delete(:type) || "string").to_s, description: spec.delete(:description).to_s }.merge(spec)
-        end
-        { type: "object", properties: properties, required: required }
-      end
-      private_class_method :params_schema
-
-      # The parameters object from schema: (a JSON Schema object).
-      def self.schema_parameters(name, schema)
-        raise ArgumentError, "tool #{name}: schema must be a Hash" unless schema.is_a?(Hash)
-
-        schema = Api.symbolize(schema)
-        raise ArgumentError, "tool #{name}: schema must be {type: \"object\", properties: {…}}" unless schema.fetch(:type, "object").to_s == "object"
-
-        properties = schema[:properties] || {}
-        raise ArgumentError, "tool #{name}: schema properties must be a Hash" unless properties.is_a?(Hash)
-
-        { type: "object", properties: properties, required: Array(schema[:required]).map(&:to_s) }
-          .merge(schema.except(:type, :properties, :required))
-      end
-      private_class_method :schema_parameters
+      # A checked tool declaration (ToolSpec.build), for bundles: the mcp
+      # bundle's token estimate calls it, installed ones included.
+      # @return [ToolSpec]
+      def self.tool_spec(...) = ToolSpec.build(...)
     end
   end
 end

data/lib/samagotchi/plugin/loader.rb

@@ -17,9 +17,11 @@ module Samagotchi
     # Engine#shutdown stops; +stage_tools+ is (bundle, specs, context),
     # chi.replace_tools' set, which the Engine applies on its turn thread;
     # +init+ adds a chi.init task (Engine#add_init_task); +toolkits+ is the
-    # Engine's list of the plugins' toolkits (chi.toolkit: Toolkit::Kit).
+    # Engine's list of the plugins' toolkits (chi.toolkit: Toolkit::Kit);
+    # +tool_index+ the Engine's Tools::ToolIndex (chi.tool_source);
+    # +peer_sources+ the Engine's PeerSources (chi.peer_source).
     Registries = Struct.new(:commands, :tools, :hooks, :context_for, :tools_changed, :services, :stage_tools, :init,
-                            :toolkits, keyword_init: true)
+                            :toolkits, :tool_index, :peer_sources, keyword_init: true)
 
     # Loads installed bundles' plugins (manifest plugin: {file:, sha256:})
     # into an Engine's registries (docs/plugins.md).