samagotchi 0.154.1 → 0.156.0

data/lib/samagotchi/tools/delegate.rb

@@ -314,11 +314,13 @@ module Samagotchi
 
       # @return [String] the child's id, or an Error: line
       def self.follow_up(task, session:, parent:, state_dir:)
-        id = Session.resolve_id(session, state_dir: state_dir)
+        id = Session.resolve!(session, state_dir: state_dir)
         child = begin
           Session.load(id, state_dir: state_dir)
-        rescue ArgumentError
-          return "Error: no session #{session} (list_sessions shows them)"
+        rescue Session::NotFound
+          raise # gone since resolve!: the outer rescue adds the list_sessions hint
+        rescue ArgumentError => e # a file that won't load
+          return "Error: #{e.message}"
         end
         unless child.parent_id == parent.id
           return "Error: #{id[0, 8]} is not a delegate of this session; send_note reaches any session"
@@ -340,6 +342,8 @@ module Samagotchi
         "Error: session #{id[0, 8]}: #{e.message}"
       rescue SessionManager::OwnedByTUI
         "Error: session #{id[0, 8]} is #{OwnerLock::TUI_BUSY}, which can't take a delegated message"
+      rescue Session::NotFound => e
+        "Error: #{e.message} (list_sessions shows them)"
       rescue Session::AmbiguousId => e
         "Error: #{e.message}"
       end
@@ -392,10 +396,11 @@ module Samagotchi
       # busy (a worker runs its turn), or running with a worker on its way
       # (ChildrenStatus asks it too).
       # @param summary [Hash] a children_of row, or the same keys: busy,
-      #   status, live, updated_at
+      #   saved_status (the file's: the displayed status shows a worker on
+      #   its way as idle), live, updated_at
       def self.running?(summary)
         return true if summary[:busy]
-        return false unless summary[:status] == Session::STATUS_RUNNING && !summary[:live]
+        return false unless summary[:saved_status] == Session::STATUS_RUNNING && !summary[:live]
 
         Time.now - Time.iso8601(summary[:updated_at].to_s) < STARTING_GRACE_SECONDS
       rescue ArgumentError

data/lib/samagotchi/tools/delegate_result.rb

@@ -29,7 +29,7 @@ module Samagotchi
                      newest_running_child(peers.session_id, state_dir: sd) ||
                        (return "No running delegate; list_sessions shows finished ones.")
                    else
-                     id = Session.resolve_id(session.to_s.strip, state_dir: sd)
+                     id = Session.resolve!(session.to_s.strip, state_dir: sd)
                      child = Session.load(id, state_dir: sd)
                      unless child.parent_id == peers.session_id
                        return "Error: #{id[0, 8]} is not a delegate of this session (list_sessions marks them child)"
@@ -38,10 +38,10 @@ module Samagotchi
                      id
                    end
         DelegateWait.call(child_id, peers: peers, timeout: Delegate.parse_timeout(timeout))
-      rescue Session::AmbiguousId => e
+      rescue Session::NotFound => e
+        "Error: #{e.message} (list_sessions shows them)"
+      rescue ArgumentError => e
         "Error: #{e.message}"
-      rescue ArgumentError
-        "Error: no session #{session.to_s.strip} (list_sessions shows them)"
       end
 
       def self.newest_running_child(parent_id, state_dir:)

data/lib/samagotchi/tools/index_hint.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Tools
+    # find_tools' answer text that the wire reads too, kept a leaf (no
+    # requires): ToolIndex writes CALL_HINT as a keyword answer's first
+    # line, and LLM::AnthropicWire strips it from a result whose tools it
+    # loads (they are called directly then).
+    module IndexHint
+      # A keyword answer's first line; call_tool is BuiltinCalls::VIA.
+      CALL_HINT = "Call one with call_tool(tool: \"<group>/<tool>\", args: {…})."
+    end
+  end
+end

data/lib/samagotchi/tools/registry.rb

@@ -2,14 +2,23 @@
 
 module Samagotchi
   module Tools
+    # A reader of the turn's tools (Tools::ToolSurface) given none: a
+    # context or call that should carry the turn's carries nothing. Never
+    # taken as a failing preview's or targets' (ToolActivity, Guardrails::
+    # Targets re-raise it): a rule's acts_as must not silently go missing.
+    class MissingSurface < StandardError
+      def initialize(msg = "no ToolSurface: the turn's tools are missing (TurnContext#surface)") = super
+    end
+
     # The tools a session offers the model, in declaration order: the
     # built-ins (Tools::Builtins) as registered, then the ones bundles add,
     # by bundle and name. That order doesn't depend on which plugin
     # finished its init first or re-registered a changed tool, so the
     # tool list (part of the prompt's cached prefix) is the same in every
-    # session with the same tools. The
-    # native prompts and the chat path's tools: are rendered from #schemas,
-    # and KernelLoop#dispatch runs a call through its entry's handler.
+    # session with the same tools. Its readers (the prompt, a turn's
+    # loops, the tool index, /toolkit) read the Tools::ToolSurface built
+    # from its lists (#entries, #reachable_names, #left_out_names,
+    # #removed_names, #stranded_names) under a toolkit and layers.
     class Registry
       # @!attribute name [String]
       # @!attribute schema [Hash] {name:, description:, parameters:}, as in
@@ -18,22 +27,45 @@ module Samagotchi
       #   "Error: …" marks a failure); kctx is the KernelLoop's ToolContext
       # @!attribute label [String, nil] the activity line's action ("calling
       #   tool" when nil); ToolActivity knows the built-ins' own
-      # @!attribute preview [#call, nil] call → the activity line's params
-      # @!attribute targets [#call, nil] call → what guardrail rules match
+      # @!attribute preview [#call, nil] (call, surface) → the activity line's
+      #   params; +surface+ the turn's Tools::ToolSurface (nil: none)
+      # @!attribute targets [#call, nil] (call, surface) → what guardrail
+      #   rules match. #register takes a one-argument preview or targets
+      #   (call only, a plugin's) and gives it this form (.per_call)
       # @!attribute refs [#call, nil] call → the row's refs (a plugin's
       #   refs:, RowRefs checks what it gives)
       # @!attribute source [String] "core", or the bundle that added it
       # @!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
-      # @!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
+      # @!attribute unwrap [#call, nil] (call, surface) → the call it stands
+      #   for under the turn's Tools::ToolSurface, 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"
 
+        # Its preview on +call+ (the row's params), nil without one.
+        # +surface+, the turn's Tools::ToolSurface (nil: none), is what
+        # call_tool's reads (what the turn reaches: it raises MissingSurface
+        # without one); a plugin's ignores it.
+        def preview_of(call, surface = nil) = preview&.call(call, surface)
+
+        # Its targets on +call+ (what guardrail rules match), nil without
+        # any; +surface+ as #preview_of.
+        def targets_of(call, surface = nil) = targets&.call(call, surface)
+
+        # +callable+ as (call, surface) → value, the one form an entry's
+        # preview and targets take: a one-argument one (call only) is given
+        # the call alone. The arity is read here, once, at registration.
+        def self.per_call(callable)
+          return callable if callable.nil? || callable.arity != 1
+
+          ->(call, _surface = nil) { callable.call(call) }
+        end
+
         # Offered in a turn under +layers+ (the turn's LLM context layers).
         def offered?(layers) = layer.nil? || Array(layers).include?(layer)
       end
@@ -43,17 +75,19 @@ module Samagotchi
       # name, and +groups+ the source groups registered when the plugins
       # loaded; +loaded+ the entries registered then (nil: whatever is
       # registered now), which alone decide whether the index's tools are
-      # needed (Registry#index_needed?). +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.
+      # needed (Registry#index_needed?). +deferrable+ (surface → the
+      # sources' tools a host that loads tools may declare deferred),
+      # +wrap+ ((call, surface) → the call_tool call a direct call of one
+      # of them runs as, or nil) and +unreached+ ((name, surface) → a
+      # source tool the toolkit doesn't reach) are nil when nothing reaches
+      # them; each is given the turn's Tools::ToolSurface.
       Index = Data.define(:source, :call_name, :groups, :deferrable, :wrap, :unreached, :loaded) do
         def initialize(source:, call_name:, groups:, deferrable: nil, wrap: nil, unreached: nil, loaded: nil)
           super(source: source, call_name: call_name, groups: Array(groups).map(&:to_s).uniq.freeze,
                 deferrable: deferrable, wrap: wrap, unreached: unreached, loaded: loaded&.dup&.freeze)
         end
 
-        def unreached_tool(name) = unreached&.call(name)
+        def unreached_tool(name, surface) = unreached&.call(name, surface)
       end
 
       def initialize
@@ -66,7 +100,7 @@ module Samagotchi
       attr_accessor :index
 
       # The session's resolved toolkit (Toolkit::Resolved), which the lists
-      # below and #offered filter by; nil declares every tool (full). The
+      # below filter by; nil declares every tool (full). The
       # Engine sets it at a turn's start, before the prompt is built, and
       # only there: a request's declared tools never change mid-turn.
       attr_accessor :toolkit
@@ -81,8 +115,9 @@ module Samagotchi
                    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, unwrap: unwrap)
+        @entries[name] = Entry.new(name: name, schema: schema, handler: handler, label: label,
+                                   preview: Entry.per_call(preview), targets: Entry.per_call(targets), refs: refs,
+                                   source: source, layer: layer, unwrap: unwrap)
       end
 
       # Remove a tool (a plugin's tool set changed after load).
@@ -94,22 +129,6 @@ module Samagotchi
 
       def key?(name) = @entries.key?(name.to_s)
 
-      # The entry +name+ names when a turn under +layers+ offers it (the
-      # one a call dispatches to).
-      # @return [Entry, nil]
-      def offered(name, layers: [])
-        entry = self[name]
-        entry if entry&.offered?(layers) && declared?(entry)
-      end
-
-      # The entry +name+ names when the session's toolkit leaves it out (a
-      # 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 && left_out?(entry, layers, @toolkit)
-      end
-
       # The tools +toolkit+ (the session's by default) leaves out of a turn
       # under +layers+. The tool index's own aren't, unless it removes them:
       # they are declared when there is something to reach.
@@ -118,14 +137,6 @@ module Samagotchi
         ordered(@entries.values.select { |entry| left_out?(entry, layers, toolkit) }).map(&:name)
       end
 
-      # The tool +name+ names (a built-in or a plugin's) 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 tools +toolkit+ leaves out of a turn under +layers+ that the tool
       # index reaches (call_tool), built-ins and plugin tools alike: not in
       # its kit's list, but not removed either (remove:, --no-tool, /toolkit
@@ -184,14 +195,23 @@ module Samagotchi
         ordered(@entries.values.select { |entry| entry.offered?(layers) && declared?(entry, toolkit) })
       end
 
-      # @return [Array<Hash>] the schemas, in declaration order
-      def schemas(layers: []) = entries(layers: layers).map(&:schema)
-
       def freeze
         @entries.freeze
         super
       end
 
+      # A frozen copy of its entry set, with its toolkit, reaching_kit and
+      # index as they are now (ToolkitBinding#publish!, on the turn thread):
+      # registering or unregistering here leaves it as it was. Shallow: the
+      # Entry Structs are this Registry's own, their fields set in place on
+      # the turn thread (Plugin::ToolSpec.apply, ToolIndex#refresh!).
+      # @return [Registry]
+      def snapshot
+        copy = dup
+        copy.instance_variable_set(:@entries, @entries.dup)
+        copy.freeze
+      end
+
       private
 
       # Declared by +toolkit+ (nil: every tool, full). The tool index's

data/lib/samagotchi/tools/send_note.rb

@@ -22,7 +22,7 @@ module Samagotchi
         return "Error: this session's id is not known here" unless peers&.session_id
         return "Error: give the target session's id (list_sessions shows them)" if session.to_s.strip.empty?
 
-        id = Session.resolve_id(session.to_s.strip, state_dir: peers.state_dir)
+        id = Session.resolve!(session.to_s.strip, state_dir: peers.state_dir)
         Session.load(id, state_dir: peers.state_dir)
         return "Error: #{id[0, 8]} is this session; send_note is for other sessions" if id == peers.session_id
 
@@ -33,12 +33,10 @@ module Samagotchi
 
         where = result.status == :queued ? "its worker adds it before its next turn" : "it has no worker now, so it waits for its next start"
         "Queued a note for session #{id[0, 8]}: #{where}. It does not start a turn there."
-      rescue Session::AmbiguousId => e
+      rescue Session::NotFound => e
+        "Error: #{e.message} (list_sessions shows them)"
+      rescue ArgumentError => e # AmbiguousId, SessionInbox::NoteRejected, a file that won't load
         "Error: #{e.message}"
-      rescue SessionInbox::NoteRejected => e
-        "Error: #{e.message}"
-      rescue ArgumentError
-        "Error: no session #{session.to_s.strip} (list_sessions shows them)"
       end
     end
   end