samagotchi 0.154.0 → 0.155.0

data/lib/samagotchi/system_prompt.rb

@@ -8,6 +8,7 @@ require_relative "memory_paths"
 require_relative "paths"
 require_relative "tool_declarations"
 require_relative "tools/memory"
+require_relative "tools/tool_surface"
 require_relative "muted_memories"
 require_relative "model_notes"
 require_relative "bundle_needs"
@@ -46,7 +47,8 @@ module Samagotchi
     attr_reader :requested_memories
 
     # @param profile  [#call] → ModelProfile
-    # @param tools    [#call] → Tools::Registry
+    # @param tools    [#call] → Tools::Registry, nil (no tools): each build
+    #   reads it as a Tools::ToolSurface under the build's layers
     # @param session  [#call] → Session, nil
     # @param thinking [#call] → Symbol, the effective model's level (Thinking)
     # @param model    [#call] → ModelIdentity, nil (the section is left out)
@@ -77,6 +79,10 @@ module Samagotchi
       # a new process. The files' text is read at each build.
       @config_appended = Degrade.call(:prompt, "appended_list_unreadable", fallback: []) { ConfigFile.appended_prompt_files }
       @cli_appended = Array(appended_files).map { |path| File.expand_path(path.to_s) }
+      # { [chat, thinking, layers] => Built }, swapped for a new one by #reset!
+      @cache = {}
+      # The Built #build returned last; nil before a build and after #reset!.
+      @last = nil
     end
 
     # @return [Array<String>] the names the session preloads, known before
@@ -85,37 +91,37 @@ module Samagotchi
       @requested_memories.map { |raw| split_memory_scope(raw).last }.uniq
     end
 
+    # A prompt #build made, with what it read while it did: the memory
+    # index sizes (#memory_index), the model notes, the files and the
+    # plugins' sections it holds, its stable part's length (chat) and the
+    # Tools::ToolSurface it declares (the tools, the not-loaded line, the
+    # kit's prompt text).
+    Built = Data.define(:prompt, :memory_index, :notes, :files, :sections, :stable_length, :surface)
+
     # The full prompt: #base wrapped with the index and the rest. Built once
     # per loop and level (until #reset!) so the prompt prefix, and the
     # server's KV cache for it, stay stable.
+    #
+    # #reset! runs on other threads (a plugin's tools_changed! /
+    # prompt_changed!, a /stats re-resolving the profile) and, through the
+    # profile lookup, inside a build on this one. So a build reads @cache
+    # once and computes into locals: a reset meanwhile swaps in a new cache
+    # and this build's result goes into the dropped one, so it is returned
+    # (the same bytes as without the reset) but not kept, and the next
+    # build reads the sources again. No lock: the build reads memory files
+    # and calls the lookups, one of which takes ModelBinding's mutex, whose
+    # holder (a /stats thread) may itself call #reset!.
     # @param chat [Boolean] for the chat loop
     # @param thinking [Symbol, nil] the level (Thinking); nil: the effective model's
     # @param layers [Array<Symbol>] the turn's LLM context layers: the
-    #   native prompt declares the tools they add (Tools::Registry#entries)
+    #   native prompt declares the tools they add (Tools::ToolSurface#declared)
     def build(chat: false, thinking: nil, layers: [])
       key = [chat, thinking, layers]
-      @built ||= {}
-      @index_sizes ||= {}
-      @notes_loaded ||= {}
-      @files_loaded ||= {}
-      @sections_loaded ||= {}
-      unless @built.key?(key)
-        @section_notes = nil
-        @section_files = []
-        @section_plugins = []
-        @built[key] = system_prompt_with_index(
-          assist_system_prompt(chat: chat, layers: layers), chat: chat, thinking: thinking, layers: layers
-        )
-        @index_sizes[key] = @measured_index
-        @notes_loaded[key] = @section_notes || []
-        @files_loaded[key] = @section_files.freeze
-        @sections_loaded[key] = @section_plugins.freeze
-      end
-      @memory_index = @index_sizes[key]
-      @prompt_notes = @notes_loaded[key]
-      @prompt_files = @files_loaded[key]
-      @prompt_sections = @sections_loaded[key]
-      @built[key]
+      cache = @cache
+      built = cache[key] || (cache[key] = build_prompt(chat: chat, thinking: thinking, layers: layers))
+      @memory_index = built.memory_index
+      @last = built
+      built.prompt
     end
 
     # The memory indexes the prompt #build returned last holds, per scope
@@ -130,7 +136,7 @@ module Samagotchi
     # (Array<ModelNotes::Note>, [] with none), nil before a build and after
     # #reset!. Read when the prompt is built, as the section is.
     # @return [Array<ModelNotes::Note>, nil]
-    attr_reader :prompt_notes
+    def prompt_notes = @last&.notes
 
     # The files whose text the prompt #build returned last holds, as
     # absolute paths in prompt order: the AGENTS.md chain, then the
@@ -138,26 +144,21 @@ module Samagotchi
     # build and after #reset!. Read when the prompt is built, as the
     # sections are.
     # @return [Array<String>]
-    def prompt_files = @prompt_files || []
+    def prompt_files = @last&.files || []
 
     # The plugins' prompt sections the prompt #build returned last holds
     # (Plugin::PromptSections::Built, prompt order), [] before a build and
     # after #reset!.
     # @return [Array<Plugin::PromptSections::Built>]
-    def prompt_sections = @prompt_sections || []
+    def prompt_sections = @last&.sections || []
 
     # Drops the built prompts: the next #build reads the profile, tools,
     # indexes and memories again (a model or profile switch, changed tools).
     def reset!
-      @built = nil
-      @index_sizes = nil
-      @notes_loaded = nil
-      @prompt_notes = nil
-      @files_loaded = nil
-      @prompt_files = nil
-      @sections_loaded = nil
-      @prompt_sections = nil
-      @stable_lengths = nil
+      # Single assignments: a build in flight keeps the cache it read
+      # (#build), so it neither fails nor is kept.
+      @cache = {}
+      @last = nil
     end
 
     # The length of +prompt+'s stable part when it is a chat prompt #build
@@ -165,12 +166,18 @@ module Samagotchi
     # a remote prompt cache can keep for every session (PromptCache). nil
     # for any other text, or a prompt without those lines.
     # @return [Integer, nil]
-    def stable_length(prompt) = @stable_lengths&.[](prompt)
+    def stable_length(prompt)
+      last = @last
+      return last.stable_length if last&.prompt == prompt
+
+      @cache.each_value.find { |built| built.prompt == prompt }&.stable_length
+    end
 
     # The base prompt (specs, plugins' declarations), with Gemma's tool
     # declarations at its end as #build has them.
     def base(chat: false, layers: [])
-      with_tail_declarations(assist_system_prompt(chat: chat, layers: layers), chat: chat, layers: layers)
+      surface = tool_surface(layers)
+      with_tail_declarations(assist_system_prompt(chat: chat, surface: surface), chat: chat, surface: surface)
     end
 
     # Names activated via preloaded --memory entries during prompt
@@ -182,6 +189,28 @@ module Samagotchi
 
     private
 
+    # One #build's work: the prompt and what it read, in a Built. The
+    # @section_* and @measured_* scratch is this build's (the turn thread's)
+    # alone: #reset! never touches it.
+    def build_prompt(chat:, thinking:, layers:)
+      @section_notes = nil
+      @section_files = []
+      @section_plugins = []
+      @measured_stable_length = nil
+      surface = tool_surface(layers)
+      prompt = system_prompt_with_index(assist_system_prompt(chat: chat, surface: surface),
+                                        chat: chat, thinking: thinking, surface: surface)
+      Built.new(prompt: prompt, memory_index: @measured_index, notes: @section_notes || [],
+                files: @section_files.freeze, sections: @section_plugins.freeze, stable_length: @measured_stable_length,
+                surface: surface)
+    end
+
+    # The session's tools as a build under +layers+ declares them, read
+    # from the Registry now (one per build: the declarations, the
+    # not-loaded line and the kit's text agree).
+    # @return [Tools::ToolSurface]
+    def tool_surface(layers) = Tools::ToolSurface.for(@tools_lookup.call, layers: layers)
+
     def profile = @profile_lookup.call
 
     def turn_thinking = @thinking_lookup.call
@@ -192,8 +221,8 @@ module Samagotchi
 
     # ── Tool declarations ──────────────────────────────────────────────────────
 
-    def tool_declarations(layers)
-      schemas = ToolDeclarations.native_schemas(@tools_lookup.call, layers: layers)
+    def tool_declarations(surface)
+      schemas = ToolDeclarations.native_schemas(surface)
       case profile.name
       when "qwen36"
         ToolDeclarations.qwen_declarations(schemas)
@@ -216,7 +245,7 @@ module Samagotchi
 
     # @param chat [Boolean] for the chat loop: no tool declarations or call
     #   syntax (its tools go as schemas with each request)
-    def assist_system_prompt(chat: false, layers: [])
+    def assist_system_prompt(surface:, chat: false)
       return chat_system_prompt if chat
 
       hint = tool_call_hint
@@ -225,7 +254,7 @@ module Samagotchi
       tools = if gemma_tail_declarations?
                 "Your tools are declared at the end of this system prompt."
               else
-                "You have access to the following tools:\n\n#{tool_declarations(layers)}\n"
+                "You have access to the following tools:\n\n#{tool_declarations(surface)}\n"
               end
 
       <<~SYS
@@ -316,7 +345,7 @@ module Samagotchi
     # memory write changes them) after all of them; the model, the location
     # and the session close the prompt (Gemma's tool declarations still
     # follow them).
-    def system_prompt_with_index(base, chat: false, thinking: nil, layers: [])
+    def system_prompt_with_index(base, chat: false, thinking: nil, surface: tool_surface([]))
       thinking_token = chat ? "" : Thinking.native(thinking || turn_thinking, profile).system_token
       indexes = { project: read_memory_index("project"), system: read_memory_index("system") }
       @measured_index = measure_indexes(indexes)
@@ -324,15 +353,15 @@ module Samagotchi
         "Project memories:\n#{indexes[:project]}",
         "System memories:\n#{indexes[:system]}"
       ].join("\n\n")
-      stable = [thinking_token + base, not_loaded_line(layers), rg_guidance, system_identity_section, model_notes_section, explicit_memory_section,
-                project_specific_description, appended_section, kit_prompt_section, plugin_prompt_section, memory_sections]
+      stable = [thinking_token + base, not_loaded_line(surface), rg_guidance, system_identity_section, model_notes_section, explicit_memory_section,
+                project_specific_description, appended_section, kit_prompt_section(surface), plugin_prompt_section, memory_sections]
       stable_text = stable.compact.join("\n")
       volatile = [participants_section, current_model, project_location, current_session].compact
-      return with_tail_declarations(stable_text, chat: chat, layers: layers) if volatile.empty?
+      return with_tail_declarations(stable_text, chat: chat, surface: surface) if volatile.empty?
 
       prompt = "#{stable_text}\n#{volatile.join("\n")}"
-      (@stable_lengths ||= {})[prompt] = stable_text.length + 1 if chat
-      with_tail_declarations(prompt, chat: chat, layers: layers)
+      @measured_stable_length = stable_text.length + 1 if chat
+      with_tail_declarations(prompt, chat: chat, surface: surface)
     end
 
     # The tools the session's toolkit leaves out, named once right after the
@@ -341,15 +370,12 @@ module Samagotchi
     # the prompt is what it was before toolkits. The ones call_tool reaches
     # and the ones the toolkit removes (only the user brings those back)
     # get a sentence each; with call_tool not declared, one list.
-    def not_loaded_line(layers)
-      registry = @tools_lookup.call
-      return nil unless registry.respond_to?(:left_out_names)
-
-      names = registry.left_out_names(layers: layers)
+    def not_loaded_line(surface)
+      names = surface.left_out.keys
       return nil if names.empty?
 
-      toolkit = "(toolkit #{registry.toolkit&.name})"
-      reachable = registry.reachable_names(layers: layers)
+      toolkit = "(toolkit #{surface.toolkit&.name})"
+      reachable = surface.index_only.map(&:name)
       if reachable.empty?
         return "Not loaded in this session #{toolkit}: #{names.join(", ")}. Only the user can load one (/toolkit add <name>)."
       end
@@ -371,10 +397,7 @@ module Samagotchi
     # sessions on that kit share it, and a memory write doesn't move it.
     # nil on a kit without one and on full: the prompt is what it was
     # before kit prompts.
-    def kit_prompt_section
-      registry = @tools_lookup.call
-      registry.respond_to?(:toolkit) ? registry.toolkit&.prompt : nil
-    end
+    def kit_prompt_section(surface) = surface.toolkit&.prompt
 
     # The plugins' prompt sections (chi.prompt_section), right after the
     # kit prompt and before the memory indexes: a plugin's text depends on
@@ -390,8 +413,8 @@ module Samagotchi
       end
     end
 
-    def with_tail_declarations(prompt, chat:, layers:)
-      chat || !gemma_tail_declarations? ? prompt : prompt.rstrip + tool_declarations(layers)
+    def with_tail_declarations(prompt, chat:, surface:)
+      chat || !gemma_tail_declarations? ? prompt : prompt.rstrip + tool_declarations(surface)
     end
 
     def gemma_tail_declarations? = profile.name == "gemma4"

data/lib/samagotchi/terminal_ui/attached_view.rb

@@ -60,15 +60,6 @@ module Samagotchi
         @screen.commit(text)
       end
 
-      # Draw on +surface+ from now on (no caller since the REPL went): what the slot shows
-      # moves there.
-      def surface=(surface)
-        @lock.synchronize do
-          @screen = surface
-          redraw_status if status_text
-        end
-      end
-
       # A new turn: its tally starts over too.
       def reset_turn_feedback
         @lock.synchronize do

data/lib/samagotchi/terminal_ui/input_support.rb

@@ -5,6 +5,7 @@ require "fileutils"
 require "reline"
 
 require_relative "../config"
+require_relative "../degrade"
 require_relative "../memory_paths"
 require_relative "../prompt_history"
 require_relative "../tools/memory"
@@ -90,20 +91,18 @@ module Samagotchi
         fragment = slash_fragment.to_s.strip
         return [] unless fragment.start_with?("/")
 
-        begin
+        # Only at the line's start: "/x" mid-line is a path, not a command.
+        Degrade.call(:attached, "completion_line_unreadable") do
           buf = Reline.line_buffer.to_s
-          if !buf.empty? && !buf.lstrip.start_with?("/")
-            return []
-          end
-        rescue StandardError
-          nil
+          return [] if !buf.empty? && !buf.lstrip.start_with?("/")
         end
 
         lowered = fragment.downcase
         return slash_commands.dup if lowered == "/"
 
         slash_commands.select { |cmd| cmd.start_with?(lowered) }
-      rescue StandardError
+      rescue StandardError => e
+        Degrade.note(:attached, "slash_completion_failed", e)
         []
       end
 
@@ -134,7 +133,8 @@ module Samagotchi
           relative_path = "#{relative_path}/" if File.directory?(absolute_path)
           "#{AT_PATH_COMPLETION_PREFIX}#{relative_path}"
         end
-      rescue StandardError
+      rescue StandardError => e
+        Degrade.note(:attached, "path_completion_failed", e)
         []
       end
 
@@ -190,7 +190,8 @@ module Samagotchi
             yield scope, name
           end
         end
-      rescue StandardError
+      rescue StandardError => e
+        Degrade.note(:attached, "memory_completion_failed", e)
         []
       end
 
@@ -207,8 +208,8 @@ module Samagotchi
         @history_signature = PromptHistory.signature
         @history_seen = PromptHistory.entries
         @history_seen.last(PromptHistory::LIMIT).each { |entry| Reline::HISTORY << entry }
-      rescue StandardError
-        nil
+      rescue StandardError => e
+        Degrade.note(:attached, "history_load_failed", e)
       end
 
       # A scratch session keeps nothing, its typed lines neither.
@@ -223,8 +224,8 @@ module Samagotchi
           history_lock.synchronize { forget_own_line(own) } if own
           raise
         end
-      rescue StandardError
-        nil
+      rescue StandardError => e
+        Degrade.note(:attached, "history_append_failed", e)
       end
 
       # Before a main-prompt read, and on the first ↑ of a walk at an open
@@ -255,8 +256,8 @@ module Samagotchi
           @history_signature = signature
           @history_seen = entries
           history_lock.synchronize { add_others_lines(fresh) }
-        rescue StandardError
-          nil
+        rescue StandardError => e
+          Degrade.note(:attached, "history_pickup_failed", e)
         end
       end
 

data/lib/samagotchi/terminal_ui/join_replay.rb

@@ -77,8 +77,11 @@ module Samagotchi
         Log.session_id = @link.client.session_id
         Log.info(:attached, "joined", session: @link.client.session_id, messages: exchange.size,
                                       notes: messages.count { |m| ContextNote.note?(m) })
-        last_user = exchange.rindex { |m| Steer.prompt?(m) }
-        render_join_notes(messages)
+        # The last turn's own prompt (Steer.turn_prompt?, as the page's
+        # turns): not Qwen's recovery line, nor input merged into the turn.
+        last_user = exchange.rindex { |m| Steer.turn_prompt?(m) }
+        from = last_user && messages.index { |m| m.equal?(exchange[last_user]) }
+        render_join_notes(messages, from)
         return unless last_user
 
         @screen.commit(join_prompt_line(exchange[last_user]))
@@ -86,7 +89,6 @@ module Samagotchi
         unless ImageRef.placeholder_only?(exchange[last_user][:content])
           Array(exchange[last_user][:images]).each { |ref| @screen.commit(format_image_line(ref)) }
         end
-        from = messages.index { |m| m.equal?(exchange[last_user]) }
         render_join_steps(messages, from, durations: join_tool_records(exchange[last_user]))
         record = @link.saved_turn_record(exchange[last_user][:turn_id] || exchange[last_user]["turn_id"])
         failed = join_failed_record(record)
@@ -114,19 +116,21 @@ module Samagotchi
                                              .find { |text| !text.empty? }
           @screen.commit(last_lines(answer)) if answer
         end
-        render_join_notes(messages, after_exchange: true)
+        render_join_notes(messages, from, after_exchange: true)
       end
 
       # What the last exchange did, as the live turn drew it: each saved
       # call's tool row (action, params, status from its result, and its
       # duration from +durations+, the turn's saved tool records) and a
-      # plugin's steer where it came. The step texts stay out, as live (the
-      # ticker's).
+      # plugin's steer and the user's input merged into the turn where they
+      # came. The step texts stay out, as live (the ticker's).
       def render_join_steps(messages, from, durations: [])
         records = durations.dup
         messages.each_with_index.drop(from + 1).each do |m, i|
           if Steer.steer?(m)
             @screen.commit(format_steer_line(source: m[:source], text: m[:content]))
+          elsif Steer.input?(m) && !Steer.turn_prompt?(m)
+            @screen.commit("input> #{m[:content]}")
           elsif %w[model assistant].include?(m[:role].to_s)
             responses = messages.drop(i + 1).take_while { |r| r[:role].to_s == "tool_response" }
             Array(MessageParts.for_message(m, responses)&.dig(:tools)).each do |part|
@@ -209,13 +213,13 @@ module Samagotchi
         format_tool_guardrail_suffix({ decided_by: "system one", p: saved["p"] || saved[:p] })
       end
 
-      # The context notes that came since the last prompt (all of them in a
-      # session with none), after the exchange the header shows.
-      def render_join_notes(messages, after_exchange: false)
-        last_user = messages.rindex { |m| Steer.prompt?(m) }
-        return if after_exchange != !last_user.nil?
+      # The context notes that came since the last prompt (+from+, its index
+      # in +messages+; all of them in a session with none), after the
+      # exchange the header shows.
+      def render_join_notes(messages, from, after_exchange: false)
+        return if after_exchange != !from.nil?
 
-        messages[(last_user ? last_user + 1 : 0)..].select { |m| ContextNote.note?(m) }.each do |m|
+        messages[(from ? from + 1 : 0)..].select { |m| ContextNote.note?(m) }.each do |m|
           @screen.commit(context_note_line(ContextNote.label_of(m), ContextNote.text_of(m)))
         end
       end

data/lib/samagotchi/terminal_ui/reline_seam.rb

@@ -44,11 +44,6 @@ module Samagotchi
         # @return [#call, nil]
         attr_accessor :interrupt_handler
 
-        # Called with no arguments for each key a read takes (typing is
-        # activity for an idle clock; nobody sets it now).
-        # @return [#call, nil]
-        attr_accessor :key_handler
-
         # @return [Boolean] a Reline read is open (it owns stdin)
         def reading? = @reading == true
 
@@ -150,11 +145,6 @@ module Samagotchi
         @rendered_screen.base_y = 0 if RelineSeam.screen
       end
 
-      def update(key)
-        RelineSeam.key_handler&.call
-        super
-      end
-
       def screen_height
         screen = RelineSeam.screen
         screen ? [super, screen.editor_budget].min : super

data/lib/samagotchi/terminal_ui/status_row.rb

@@ -54,13 +54,6 @@ module Samagotchi
         @shown = nil
       end
 
-      # The surface it draws on (no caller since the REPL went): the row
-      # is drawn there at the next change.
-      def surface=(surface)
-        @surface = surface
-        @shown = nil
-      end
-
       def [](field) = @values[field]
 
       # Change some fields; the row is redrawn when its text changed.

data/lib/samagotchi/testing/boundary.rb

@@ -94,6 +94,13 @@ module Samagotchi
           "Samagotchi::AnswerRefs.new" => "spec: after_turn's refs: helper, as chi's fire site builds it",
           "Samagotchi::Log" => "spec: stubs Log to check what ctx.log recorded: a kit log recorder could replace it"
         },
+        "inline-widgets" => {
+          'require "samagotchi/inline_widgets"' => "spec: for InlineWidgets",
+          "Samagotchi::InlineWidgets.parse" => "spec: each example the sections teach parses strictly, as chi web " \
+                                               "parses a block (the drawing is core's, so is the parse)",
+          "Samagotchi::Plugin::PromptSections::MAX" => "spec: the prompt-section limit a section over is dropped at: " \
+                                                       "could be a stable constant"
+        },
         "loop-guard" => {
           'require "samagotchi/llm/native_tool_normalizer"' => "spec: for NativeToolNormalizer",
           "Samagotchi::LLM::NativeToolNormalizer.normalize" => "spec: replays recorded calls in the shape chi's parser gives",

data/lib/samagotchi/testing/bundle.rb

@@ -11,6 +11,7 @@ require_relative "../tools/tool_index"
 require_relative "../peer_sources"
 require_relative "../toolkit"
 require_relative "../guardrails/gate"
+require_relative "../turn_context"
 require_relative "../memory_bundle/manifest"
 require_relative "../memory_bundle/source"
 require_relative "../session_setup"
@@ -239,8 +240,9 @@ module Samagotchi
         dispatched = nil
         capture = Hooks::Registry.new
         capture.register(:before_tool_call) { |event| dispatched = event.dup }
-        gate = Guardrails::Gate.new(-> { capture }, context_lookup: -> { context }, tools_lookup: -> { tools })
-        gate.evaluate(call, iteration: iteration, params: params, verdict: verdict || Verdict.new(call: call))
+        gate = Guardrails::Gate.new(hooks: capture, tools: tools, context_for: ->(_turn) { context })
+        gate.evaluate(call, context: TurnContext.none, iteration: iteration, params: params,
+                            verdict: verdict || Verdict.new(call: call))
         raise ArgumentError, "guardrails did not dispatch a before_tool_call event for #{call[:name].inspect}" unless dispatched
 
         dispatched.slice(:type, :iteration, :call, :params, :blocked, :block_reason, :guardrail, :context, :targets)
@@ -256,11 +258,11 @@ module Samagotchi
       def tool_call(call, params: nil, cwd: nil, context: nil, verdict: nil, iteration: 1)
         context ||= Guardrails::Context.new(cwd: cwd || @recorder[:cwd], session_id: @recorder[:session_id],
                                             interface: @recorder[:frontend])
-        gate = Guardrails::Gate.new(-> { hooks }, context_lookup: -> { context }, tools_lookup: -> { tools },
-                                                  checks_lookup: -> { [] })
+        gate = Guardrails::Gate.new(hooks: hooks, tools: tools, context_for: ->(_turn) { context },
+                                    checks_for: ->(_turn) { [] })
         verdict ||= Verdict.new(call: call)
         params ||= "#{call[:name]} #{call[:content] || call[:path]}".strip
-        failing { gate.evaluate(call, iteration: iteration, params: params, verdict: verdict) }
+        failing { gate.evaluate(call, context: TurnContext.none, iteration: iteration, params: params, verdict: verdict) }
       end
 
       # Run a command line ("/name args") as chi does: the first matching

data/lib/samagotchi/testing/install.rb

@@ -31,7 +31,7 @@ module Samagotchi
       # What a bundle registered (#registered): commands, tools (names),
       # hooks per event, inits (labels), toolkits, tool sources and peer
       # sources (names).
-      Registered = Data.define(:commands, :tools, :hooks, :inits, :toolkits, :tool_sources, :peer_sources)
+      Registered = Data.define(:commands, :tools, :hooks, :inits, :toolkits, :tool_sources, :peer_sources, :prompt_sections)
       # A command: its mid_turn policy and its selection-bar labels (chi.annotation).
       Command = Data.define(:name, :mid_turn, :labels)
       # A hook on an event: the bundle, the hook (its file, or the plugin's) and its priority.
@@ -98,7 +98,8 @@ module Samagotchi
           inits: inits.map { |init| init[:label] },
           toolkits: Array(registries.toolkits).map(&:name),
           tool_sources: registries.tool_index.sources.map(&:label),
-          peer_sources: registries.peer_sources.names
+          peer_sources: registries.peer_sources.names,
+          prompt_sections: registries.prompt_sections.names(name)
         )
       end
 

data/lib/samagotchi/tool_activity.rb

@@ -58,11 +58,11 @@ module Samagotchi
     # @param registry [Tools::Registry, nil] the session's tools
     # @param cwd [String, nil] what a file tool's title is relative to (the
     #   worker runs in its session's working directory)
-    def tool_activity_event(tool_name, call, result, registry: nil, cwd: Dir.pwd)
+    def tool_activity_event(tool_name, call, result, registry: nil, cwd: Dir.pwd, surface: nil)
       event = {
         action: tool_activity_action(tool_name, registry: registry, call: call),
         tool: tool_name,
-        params: tool_activity_params(tool_name, call, registry: registry),
+        params: tool_activity_params(tool_name, call, registry: registry, surface: surface),
         status: tool_activity_status(result, tool_name, command: call.is_a?(Hash) ? call[:content] : nil)
       }
       # A grep that found nothing: ok, and the web row says "no match".
@@ -359,7 +359,9 @@ module Samagotchi
       name == "git" && args.first == "diff" && args.intersect?(%w[--quiet --exit-code])
     end
 
-    def tool_activity_params(tool_name, call, registry: nil)
+    # +surface+: the turn's Tools::ToolSurface, for a preview that reads it
+    # (call_tool's); nil outside a turn.
+    def tool_activity_params(tool_name, call, registry: nil, surface: nil)
       case tool_name
       when Tools::Execute::NAME
         "command=#{preview_tool_param(call[:content])}"
@@ -453,7 +455,7 @@ module Samagotchi
         parts << "options=#{preview_tool_param(Array(opts).join(","))}" if opts && !Array(opts).empty?
         parts.join(" ")
       else
-        registry_params(registry_entry(registry, tool_name), call)
+        registry_params(registry_entry(registry, tool_name), call, surface)
       end
     end
 
@@ -472,13 +474,13 @@ module Samagotchi
     # the web's reload also has); nil for a tool the registry doesn't know
     # that has no args:, and for a built-in without its own words above
     # (the reminder tools).
-    def registry_params(entry, call)
+    def registry_params(entry, call, surface = nil)
       return nil if entry&.core?
       return nil if entry.nil? && !call[:args].is_a?(Hash)
 
       if entry&.preview
         begin
-          return entry.preview.call(call)
+          return entry.preview_of(call, surface)
         rescue StandardError => e
           Log.warn(:plugins, "plugin_preview_failed", tool: entry.name, error: e.class.name,
                                                       msg: "#{entry.name} preview failed: #{e.message}")

data/lib/samagotchi/tool_declarations.rb

@@ -635,10 +635,10 @@ module Samagotchi
 
     # The schemas the native (Gemma, Qwen) prompts declare: the built-ins
     # as they are, and each plugin tool's flattened (.flat_schema).
-    # @param registry [Tools::Registry]
-    # @param layers [Array<Symbol>] the turn's LLM context layers (Registry#entries)
-    def native_schemas(registry, layers: [])
-      registry.entries(layers: layers).map { |entry| entry.core? ? entry.schema : flat_schema(entry.schema) }
+    # @param surface [Tools::ToolSurface] the tools a turn (or a build
+    #   under its layers) declares (ToolSurface#declared)
+    def native_schemas(surface)
+      surface.declared.map { |entry| entry.core? ? entry.schema : flat_schema(entry.schema) }
     end
 
     # A plugin tool's schema in the shape the built-ins have, which is all

data/lib/samagotchi/tool_response.rb

@@ -34,14 +34,15 @@ module Samagotchi
     # own go to +on_stream_event+. An Interrupt (Ctrl-C) mid-batch yields an
     # #interrupted run for every call left (the one it cut short too), so
     # the loop's conversation answers each call, then goes on up: the turn
-    # keeps its progress (Engine#ctrl_c_messages).
+    # keeps its progress (Engine#ctrl_c_messages). +context+: the calls'
+    # turn (TurnContext), each run's (ToolRunner#run).
     # @return [Array<ToolRun>] the runs
-    def run_batch(runner, calls, iteration:, emit:, on_stream_event:, cap:)
+    def run_batch(runner, calls, context:, iteration:, emit:, on_stream_event:, cap:)
       # Before anything can be interrupted: the rescue counts it.
       runs = []
       emit.call({ type: :tool_dispatch_started, iteration: iteration, call_count: calls.length })
       calls.each_with_index do |call, index|
-        runs << runner.run(call, iteration: iteration, call_index: index + 1, call_count: calls.length,
+        runs << runner.run(call, context: context, iteration: iteration, call_index: index + 1, call_count: calls.length,
                                  on_stream_event: on_stream_event, max_tool_output_chars: cap)
         yield runs.last, index if block_given?
       end