samagotchi 0.155.0 → 0.157.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,7 +12,7 @@ require_relative "../plugin/tool_spec"
 
 module Samagotchi
   module Tools
-    # Read only when a reader asks (#live_surface, a handler): the bundle
+    # 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__)
 
@@ -27,12 +28,14 @@ module Samagotchi
     # 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: the turn's
-    # (TurnContext#surface) where the caller has one (the two tools'
-    # handlers, through their ToolContext; #unwrap, #wrap, #deferrable and
-    # #unreached_tool, given it by the runner and the deferred list), else
-    # the Registry #declare registered in, read now (#live_surface: at
-    # load, a turn's start, a guardrail rule's targets, ctx.load_tools).
+    # 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
@@ -69,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" }
@@ -264,7 +265,7 @@ module Samagotchi
       # +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 = live_surface)
+      def all_groups(surface)
         own = registry_groups(surface)
         taken = own.map(&:name) | RESERVED_GROUPS
         kept = @sources.flat_map(&:groups).select do |group|
@@ -280,7 +281,7 @@ module Samagotchi
 
       # The groups +surface+'s toolkit reaches (#all_groups' own, and the
       # source groups #declare found that it reaches).
-      def reached_groups(surface = live_surface)
+      def reached_groups(surface)
         groups = all_groups(surface)
         toolkit = surface.toolkit
         return groups if toolkit.nil? || toolkit.groups == :all
@@ -299,10 +300,11 @@ module Samagotchi
       # @return [Array<String>] the names registered
       def declare(registry, failures: nil)
         @registry = registry
-        @described = description_lines(all_groups(live_surface).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",
@@ -320,7 +322,7 @@ module Samagotchi
                                              wrap: ->(call, surface) { wrap(call, surface) },
                                              unreached: ->(name, surface) { unreached_tool(name, surface) },
                                              loaded: loaded)
-        declared!(declared)
+        declared!(declared, ToolSurface.for(registry))
         declared.map(&:name)
       end
 
@@ -331,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
@@ -357,7 +360,7 @@ 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(surface = live_surface)
+      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(surface)).values + described_groups(surface).values).join("\n")}"
@@ -370,7 +373,7 @@ module Samagotchi
       # name before it was +group+: a model that still gives it is told
       # every group was searched. +surface+: the turn's (the handler's).
       # @return [FoundText]
-      def find(query, only = nil, server: nil, surface: live_surface)
+      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?
 
@@ -384,7 +387,7 @@ module Samagotchi
       # 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).
       # +surface+: the turn's (the handler's).
-      def call(name, args, surface: live_surface)
+      def call(name, args, surface:)
         tool = lookup(name, surface)
         return tool if tool.is_a?(String)
 
@@ -420,7 +423,7 @@ module Samagotchi
       # 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, surface = live_surface)
+      def unwrap(call, surface)
         return nil unless surface.declared_entry(CALL_NAME)
 
         args = call[:args].is_a?(Hash) ? call[:args] : {}
@@ -439,7 +442,7 @@ 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(surface = live_surface)
+      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
@@ -455,7 +458,7 @@ 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, surface = live_surface)
+      def deferred_name(name, surface)
         name = name.to_s.strip
         bare = name.delete_prefix("#{CHI_GROUP}/")
         return bare if surface.indexed_entry(bare)
@@ -469,7 +472,7 @@ module Samagotchi
       # 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, surface = live_surface)
+      def unreached_tool(name, surface)
         name = name.to_s.strip
         return nil if name.empty?
 
@@ -491,7 +494,7 @@ module Samagotchi
       # loads tools): the call tool's row, rules and approvals. Nil for any
       # other call.
       # @return [Hash, nil]
-      def wrap(call, surface = live_surface)
+      def wrap(call, surface)
         name = call[:name].to_s
         return nil if name.empty? || surface.registered?(name)
 
@@ -502,7 +505,7 @@ module Samagotchi
 
       # The call tool's activity row: <group>/<tool> and its arguments, as
       # +surface+ (the turn's) reaches it.
-      def call_preview(args, surface = live_surface)
+      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)
@@ -515,7 +518,7 @@ module Samagotchi
       # 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). +surface+: the turn's (the gate's).
-      def call_targets(args, surface = live_surface)
+      def call_targets(args, surface)
         name = args["tool"].to_s.strip
         tool = lookup_quietly(name, surface)
         acts_as, label = tool ? [tool.acts_as, "#{tool.group}: #{tool.name}"] : claimed(name, surface)
@@ -526,44 +529,41 @@ module Samagotchi
 
       private
 
-      # The Registry #declare registered in, read now as a ToolSurface (its
-      # toolkit, every layer's tools left aside: the index's own group never
-      # holds one): what a caller without a turn's surface sees.
-      # @return [ToolSurface]
-      def live_surface = ToolSurface.for(@registry)
-
       # 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 (the ToolContext's: a bare kernel's computed on read; none,
-      # a spec's nil, reads the Registry now), and call_tool's preview and
-      # targets, given the turn's surface by the row and the gate
-      # (Registry::Entry#preview_of / #targets_of; nil: the Registry now).
+      # 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 || live_surface))
+          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 || live_surface) },
-                     targets: ->(call, surface = nil) { call_targets(args.call(call), surface || live_surface) })
+        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
 
-      def find_spec
-        Plugin::ToolSpec.build(FIND_NAME, find_description, params: FIND_PARAMS,
+      # 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, surface|
-          find(args["query"].to_s, args["group"], server: args["server"], surface: surface)
+                                                           }) 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, surface|
-          call(args["tool"].to_s, args["args"], surface: surface)
+        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
 
@@ -590,7 +590,7 @@ 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")}",
+        FoundText.new("#{IndexHint::CALL_HINT}\n\n#{blocks.join("\n\n")}",
                       loadable(matches, surface))
       end
 
@@ -608,11 +608,12 @@ module Samagotchi
         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
 

data/lib/samagotchi/tools/tool_surface.rb

@@ -2,6 +2,7 @@
 
 require_relative "builtin_calls"
 require_relative "deferred_tools"
+require_relative "registry"
 
 module Samagotchi
   module Tools
@@ -14,8 +15,10 @@ module Samagotchi
     # tool_definitions/deferred_tools and ToolRunner's left-out, unwrap
     # and refusal checks read it. A change made while the turn runs (a
     # /toolkit change, chi.replace_tools: staged anyway) shapes the next
-    # turn's surface only. Outside a turn (a bare kernel, a spec) a reader
-    # computes one on read (.of): nothing is cached or invalidated.
+    # turn's surface only. Outside a turn a caller builds one (.for): a bare
+    # kernel or loop at its own context (KernelLoop#own_context), the tool
+    # index at load and at #refresh!, the readers off the turn thread from
+    # ToolkitBinding#published.
     #
     # +declared+    the entries the request declares, in prompt order (Registry#entries)
     # +index_only+  the entries the toolkit leaves out that call_tool reaches (Registry#reachable_names)
@@ -67,14 +70,25 @@ module Samagotchi
               layers: frozen_copy(Array(layers)), **)
       end
 
-      # The turn's surface (+context+'s, an Engine turn's), else one computed
-      # now from +registry+ under +context+'s layers and loads_tools (a bare
-      # kernel or loop, a spec).
+      # The turn's surface (+context+'s: an Engine turn's, or a bare kernel's
+      # or loop's own, KernelLoop#own_context); a context without one raises
+      # MissingSurface (no reader falls back to the Registry as it is now).
       # @param context [TurnContext]
       # @return [ToolSurface]
-      def self.of(context, registry)
-        context.surface || self.for(registry, layers: context.llm_context_layers,
-                                              loads_tools: context.settings&.loads_tools == true)
+      def self.of(context) = context.surface || raise(MissingSurface)
+
+      # A bare kernel's or loop's own +context+ (no Engine turn: a spec, a
+      # bench) with a surface: its own, else one built now from +registry+
+      # under its layers and loads_tools. Only their own default context
+      # goes through here (KernelLoop#own_context, ChatLoop#turn_context);
+      # a context handed down is read as it is (.of).
+      # @param context [TurnContext]
+      # @return [TurnContext]
+      def self.bare(context, registry)
+        return context if context.surface
+
+        context.with(surface: self.for(registry, layers: context.llm_context_layers,
+                                                 loads_tools: context.settings&.loads_tools == true))
       end
 
       def self.empty(layers, loads_tools)

data/lib/samagotchi/turn_context.rb

@@ -32,7 +32,8 @@ module Samagotchi
   #   rules' models:), +model_name+ the bare model name the gate's rules match: frozen at
   #   Engine#generate with the settings (a before_turn hook may switch the model)
   # +surface+    the turn's Tools::ToolSurface (what its loops declare, defer and dispatch):
-  #   nil until Engine#generate builds it; a reader without one computes one (ToolSurface.of)
+  #   nil until Engine#generate builds it; a reader given none raises Tools::MissingSurface
+  #   (ToolSurface.of), a bare kernel's or loop's own context builds one (ToolSurface.bare)
   #
   # Only the turn thread replaces it (TurnState#replace_context), one frozen
   # value per write; other threads read the published one (Engine#turn_context,

data/lib/samagotchi/turn_stages/context_judge.rb

@@ -19,24 +19,22 @@ module Samagotchi
     # its pass at an owner turn's start and for a late candidate, the asks it
     # starts, and the cards an answer brought while a turn ran, shown once it
     # has ended. Its state is those held cards, under their mutex.
+    #
+    # Its two callables are read on the asks' thread, after the call that
+    # started the asks returned (an answer comes when it comes): which
+    # session the Engine is on then, and the card shown where cards go then.
     class ContextJudge
       # @param side_judgments [SideJudgments] the Engine's side asks (:context kind)
       # @param host_registry [HostRegistry] System 1's client resolves its host here
-      # @param state_dir [#call] the sessions dir
-      # @param recording [#call] (client, judgment, session, mode:) → the client saving its runs
-      # @param session [#call] the session the Engine is on now (nil: none)
-      # @param messages [#call] the owner's conversation so far (Engine#plugin_messages)
-      # @param turn_running [#call] whether a turn runs now
-      # @param show_card [#call] (**card) shows a card (Engine#show_card)
-      def initialize(side_judgments:, host_registry:, state_dir:, recording:, session:, messages:, turn_running:, show_card:)
+      # @param turn_state [TurnState] whether a turn runs as an answer comes (#running?)
+      # @param show_card [#call] (**card) shows a card (Engine#show_card: EventRoutes, on the caller's thread)
+      # @param current_session [#call] the session the Engine is on as an answer comes (nil: none)
+      def initialize(side_judgments:, host_registry:, turn_state:, show_card:, current_session:)
         @side_judgments = side_judgments
         @host_registry = host_registry
-        @state_dir = state_dir
-        @recording = recording
-        @session = session
-        @messages = messages
-        @turn_running = turn_running
+        @turn_state = turn_state
         @show_card = show_card
+        @current_session = current_session
         # On mode's cards an answer brought while a turn ran: shown once it
         # has ended (#show_cards_after_turn).
         @cards_after_turn = []
@@ -51,23 +49,28 @@ module Samagotchi
       # (ContextCandidatesLog#look) and, unless context.candidates.mode is
       # off, the proposed candidates due an ask are asked about the owner's
       # prompts so far, this one included. Never a participant's turn, a
-      # review session or a Continue (no new prompt).
-      def start(turn)
+      # review session or a Continue (no new prompt). The sessions dir is
+      # the turn's (TurnContext#state_dir).
+      # @param recorder [SystemOne::Recorder] the asks' runs (built for this call)
+      def start(turn, recorder:)
         session = turn.session
         return unless turn.prompt.is_a?(String) && OwnerPrompt.turn?(session: session, author: turn.origin.author)
 
-        pass(session, ContextCandidates.owner_texts(session.messages) + [turn.prompt], phase: "turn")
+        pass(session, ContextCandidates.owner_texts(session.messages) + [turn.prompt], phase: "turn",
+                                                                                         state_dir: turn.context.state_dir, recorder: recorder)
       end
 
       # A late proposal no owner prompt mentions (Plugin::Host
       # #candidate_proposed: github-pr's init task runs beside the first
       # turn): judged on the owner's prompts so far, the running turn's too.
-      def late_candidates
-        session = @session.call
-        return if session.nil? || session.review?
-
-        texts = ContextCandidates.owner_texts(@messages.call)
-        pass(session, texts, phase: "late") unless texts.empty?
+      # The caller (Engine#judge_late_candidates) gives the session the
+      # Engine is on, never nil nor a review session.
+      # @param messages [Array<Hash>] the owner's conversation so far (Engine#plugin_messages)
+      # @param recorder [SystemOne::Recorder] the asks' runs (built for this call)
+      # @param state_dir [String] the sessions dir
+      def late_candidates(session, messages:, recorder:, state_dir:)
+        texts = ContextCandidates.owner_texts(messages)
+        pass(session, texts, phase: "late", state_dir: state_dir, recorder: recorder) unless texts.empty?
       end
 
       # The cards #choice held while a turn ran (Engine#run_turn's ensure,
@@ -83,27 +86,27 @@ module Samagotchi
 
       # One look at +session+'s candidates; the asks go to SideJudgments'
       # :context kind, one thread asking each due candidate in turn.
-      def pass(session, texts, phase:)
+      def pass(session, texts, phase:, state_dir:, recorder:)
         return if session.id.nil? || session.scratch
 
-        rows = ContextCandidates.with_status(session.id, project_root: session.project_root, state_dir: @state_dir.call)
+        rows = ContextCandidates.with_status(session.id, project_root: session.project_root, state_dir: state_dir)
         return if rows.empty?
 
-        log = ContextCandidatesLog.log_for(@state_dir.call)
+        log = ContextCandidatesLog.log_for(state_dir)
         records = ContextCandidatesLog.records_for(log, session.id)
         ContextCandidatesLog.look(log, session.id, rows, records) if phase == "turn"
         settings = Samagotchi::ContextJudge::Settings.from_config
         return if settings.mode == "off"
 
         jobs = Samagotchi::ContextJudge.jobs(rows, records, session_id: session.id, texts: texts, settings: settings,
-                                                            phase: phase, parent_attached: parent_attached(session))
+                                                            phase: phase, parent_attached: parent_attached(session, state_dir))
         return if jobs.empty?
 
-        client = @recording.call(SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :context),
-                                 Samagotchi::ContextJudge::JUDGMENT, session, mode: settings.mode)
+        client = recorder.wrap(SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :context),
+                               Samagotchi::ContextJudge::JUDGMENT, session, mode: settings.mode)
         return unless client
 
-        start_asks(client, jobs, log, settings, choice(session, log, settings))
+        start_asks(client, jobs, log, settings, choice(session, log, settings, state_dir))
       rescue StandardError => e
         Samagotchi::ContextJudge.warn(e)
       end
@@ -128,16 +131,15 @@ module Samagotchi
       # and not in a running turn (it isn't the turn's: no "waiting for you"
       # on it), but once it has ended.
       # @return [#call] (job, fields)
-      def choice(session, log, settings)
+      def choice(session, log, settings, state_dir)
         session_id = session.id
         project_root = session.project_root
-        state_dir = @state_dir.call
         show = lambda do |**card|
-          current = @session.call
+          current = @current_session.call
           next nil unless current.nil? || current.id == session_id
 
           @cards_mutex.synchronize do
-            next @cards_after_turn << card if @turn_running.call
+            next @cards_after_turn << card if @turn_state.running?
 
             @show_card.call(**card)
           end
@@ -151,15 +153,15 @@ module Samagotchi
       # A delegate child's parent's sources, by title (else name): the
       # judge's started_from. nil for any other session (a chi send --new
       # session has no parent; a fork isn't a delegate).
-      def parent_attached(session)
+      def parent_attached(session, state_dir)
         return nil unless session.delegate? && session.parent_id
 
-        parent_root = if Session.exist?(session.parent_id, state_dir: @state_dir.call)
-                        Session.load(session.parent_id, state_dir: @state_dir.call).project_root
+        parent_root = if Session.exist?(session.parent_id, state_dir: state_dir)
+                        Session.load(session.parent_id, state_dir: state_dir).project_root
                       else
                         session.project_root
                       end
-        ContextSources.attached(session.parent_id, project_root: parent_root, state_dir: @state_dir.call)
+        ContextSources.attached(session.parent_id, project_root: parent_root, state_dir: state_dir)
                       .map { |attached| attached.source.title || attached.name }
       rescue StandardError => e
         Log.warn(:context, "context_parent_attached_failed", error: e.class.name, msg: e.message.to_s[0, 200])