samagotchi 0.65.0 → 0.67.0

data/lib/samagotchi/plugin/api.rb

@@ -1,11 +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
@@ -14,8 +15,8 @@ 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
 
       # @param bundle [String]
       # @param label [String] "<file> (bundle <name>)": what hooks and
@@ -29,9 +30,13 @@ module Samagotchi
         @context = context
         @hooks = []
         @commands = []
+        @annotations = []
         @tools = []
         @services = []
         @inits = []
+        @toolkits = []
+        @peer_sources = []
+        @tool_source = nil
         @committed = false
       end
 
@@ -63,6 +68,35 @@ module Samagotchi
         nil
       end
 
+      # A pill in the web's selection bar: it prepares +command+ (a command
+      # line) with +template+ filled from the selected text on the lines
+      # under it ({quote}: the labelled quote block Annotate makes, {text}:
+      # the selection alone, {source}: answer, thinking, step, tool or
+      # user), and fills the composer with it, or sends it at once with
+      # +send+ (docs/plugins.md). Web only.
+      # @param label [String] the pill's text, 1–40 characters
+      # @param command [String] "/name" or "/name words": a command this
+      #   plugin registers (checked once #register returns, so the order
+      #   doesn't matter; another's is a load error)
+      # @param template [String] what goes under the command line
+      # @param send [Boolean] send at once instead of filling the composer
+      def annotation(label, command:, template: "{quote}", send: false)
+        label = label.to_s.strip
+        unless label.length.between?(1, ANNOTATION_LABEL_MAX)
+          raise ArgumentError, "annotation label #{label.inspect} must be 1 to #{ANNOTATION_LABEL_MAX} characters"
+        end
+
+        line = command.to_s.strip
+        name = line.split(/\s/, 2).first.to_s
+        raise ArgumentError, "annotation #{label}: command #{line.inspect} must start with a /name" unless name.match?(COMMAND_NAME)
+        raise ArgumentError, "annotation #{label}: template must be a non-blank String" unless template.is_a?(String) && !template.strip.empty?
+        raise ArgumentError, "at most #{ANNOTATIONS_MAX} annotations per plugin" if @annotations.size >= ANNOTATIONS_MAX
+
+        @annotations << { name: name, annotation: Commands::Registry::Annotation.new(label: label, line: line, template: template,
+                                                                                     sends: send ? true : false) }
+        nil
+      end
+
       # A tool the model can call: the block gets the call's arguments (a
       # frozen Hash, string keys, typed by the schema: see Tools::Args) and
       # the Context, and returns the result text ("Error: …" marks a
@@ -83,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
@@ -111,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
@@ -119,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
@@ -128,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
@@ -215,16 +249,88 @@ module Samagotchi
         nil
       end
 
-      # Register what was staged. Called by Loader after #register.
+      # 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,
+      # toolkit.default, ctx.use_toolkit): +base+'s tools (a toolkit chi or
+      # a bundle has) with +add+ declared and +remove+ left out. A name chi
+      # (full, lean, child) or another bundle has is a load error; a base
+      # that doesn't resolve leaves the sessions on it with every tool
+      # (Toolkit#resolve).
+      def toolkit(name, base:, add: [], remove: [])
+        name = name.to_s
+        raise ArgumentError, "toolkit name #{name.inspect} must be a-z, 0-9, _ and -" unless name.match?(TOOLKIT_NAME)
+        raise ArgumentError, "this chi has no toolkits (plugins: false)" unless @registries.toolkits
+        if Toolkit::BUILTIN_KITS.key?(name)
+          raise ArgumentError, "toolkit #{name} is chi's own"
+        elsif (taken = @registries.toolkits.find { |kit| kit.name == name })
+          raise ArgumentError, "toolkit #{name} is already declared (#{taken.source})"
+        end
+        raise ArgumentError, "toolkit #{name} is declared twice" if @toolkits.any? { |kit| kit.name == name }
+
+        @toolkits << Toolkit::Kit.new(name: name, base: base, add: add, remove: remove, source: @bundle)
+        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]
-          @registries.commands.register(cmd[:name], cmd[:description], anytime: cmd[:anytime], source: @bundle) do |args|
+          annotations = @annotations.select { |item| item[:name] == cmd[:name] }.map { |item| item[:annotation] }
+          @registries.commands.register(cmd[:name], cmd[:description], anytime: cmd[:anytime], source: @bundle,
+                                                                       annotations: annotations) do |args|
             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.
@@ -243,156 +349,32 @@ module Samagotchi
             block.call(context)
           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, tools: @tools.size, hooks: @hooks.size, services: @services.size,
-                     inits: @inits.size }
-
-      # 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
+      def counts = { commands: @commands.size, annotations: @annotations.size, tools: @tools.size, hooks: @hooks.size,
+                     services: @services.size, inits: @inits.size, toolkits: @toolkits.size,
+                     tool_sources: @tool_source ? 1 : 0, peer_sources: @peer_sources.size }
 
-      # 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.entries.each do |entry|
-          next unless entry.source == bundle
-
-          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
+      # Each annotation's command is one #command staged.
+      def check_annotations!
+        names = @commands.map { |cmd| cmd[:name] }
+        @annotations.each do |item|
+          next if names.include?(item[:name])
 
-          registry.unregister(entry.name)
-          changed = true
+          raise ArgumentError, "annotation #{item[:annotation].label}: #{item[:name]} is not a command this plugin registers"
         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
+      private :check_annotations!
 
-      # 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/context.rb

@@ -29,9 +29,13 @@ module Samagotchi
     # (reason, label), each true when it acted on a running turn.
     # +frontend+ returns the Engine's interface (:repl, :worker,
     # :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).
     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, keyword_init: true)
+                      :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit,
+                      keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -109,6 +113,23 @@ module Samagotchi
       #   current_model_only names it
       def model_key = @host.model_key&.call
 
+      # @return [String, nil] the name of the session's toolkit ("full" for
+      #   one from before toolkits; nil with no session)
+      def toolkit = @host.toolkit&.call
+
+      # @return [Array<String>] the tools the session's next turn declares
+      #   (its toolkit resolved: a kit name says less than this)
+      def declared_tools = Array(@host.declared_tools&.call)
+
+      # Put the session on toolkit +name+ (a plugin's chi.toolkit, or
+      # chi's): only before the session's first model reply and never while
+      # a turn runs, since the declared tools start every request; it then
+      # applies at the next turn's start, and the user is told. Otherwise
+      # nothing changes and the plugin can say to run /toolkit NAME.
+      # @return [Boolean] whether it was staged
+      # @raise [ArgumentError] a toolkit no one declared
+      def use_toolkit(name) = !!@host.use_toolkit&.call(name.to_s)
+
       # Whether the session is a `chi scratch` one (deleted when it ends).
       def scratch? = !!@host.scratch&.call
 

data/lib/samagotchi/plugin/loader.rb

@@ -16,9 +16,12 @@ module Samagotchi
     # (the Engine's system prompts); +services+ (Plugin::Services) is what
     # 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).
+    # +init+ adds a chi.init task (Engine#add_init_task); +toolkits+ is the
+    # 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,
-                            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).