samagotchi 0.154.1 → 0.156.0

data/lib/samagotchi/session_metrics.rb

@@ -142,7 +142,7 @@ module Samagotchi
       :cached_sum,
       :cache_write_sum,
       # What the server prefilled again of the previous request's prompt
-      # (KernelLoop#reprefilled_tokens; an LLM context edit's cache break).
+      # (ReprefillMeter#tokens; an LLM context edit's cache break).
       :reprefill_sum,
       :reasoning_sum,
       :cost_sum,

data/lib/samagotchi/sessions_command.rb

@@ -302,7 +302,7 @@ module Samagotchi
         waiting = s.waiting_question(live: !!live)
         status = if waiting&.dig(:relayed_to) then "waiting (in parent #{waiting[:relayed_to]})"
                  elsif waiting then "waiting"
-                 else s.status
+                 else s.displayed_status(owner: Samagotchi::SessionManager.session_owner(s.id, state_dir: state_dir))
                  end
         "#{s.id}  #{status.ljust(8)}  #{ctx.call(s).ljust(8)}  #{s.updated_at}  #{list_text.call(s)}#{flag}#{child}"
       end

data/lib/samagotchi/share_command.rb

@@ -101,7 +101,7 @@ module Samagotchi
       error_line("#{command_name}: #{e.message}")
       CLI::Exit::FAILED
     rescue ArgumentError => e
-      error_line("#{command_name}: #{e.is_a?(Session::AmbiguousId) ? e.message : e.message.sub(/\ASession not found: /, "no session ")}")
+      error_line("#{command_name}: #{e.message}")
       CLI::Exit::FAILED
     end
 

data/lib/samagotchi/starting_marker.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+require_relative "atomic_file"
+require_relative "session"
+
+module Samagotchi
+  # A continue's "starting" marker on its new link: written before the
+  # continue moves delegates there (ChildMove) and spawns the link's worker,
+  # removed by that worker once it holds the owner lock (Worker#start). While
+  # it is #fresh?, nothing else spawns a worker for the link (SpawnPart's
+  # resume_session and wake_for_report): a ring from a moved child must not
+  # start a second one. CROSS-VERSION: the file name and its {pid, at} are
+  # read and cleared by other chi versions (spec/worker_contract_spec.rb).
+  module StartingMarker
+    # <new link dir>/starting: {pid, at}, from the move to the worker's spawn.
+    FILE = "starting"
+    # A starting marker older than this, or whose process is gone, is left
+    # over from a continue that died: it holds nothing back.
+    STALE = 60.0
+
+    module_function
+
+    # Hold off a worker for the continue's new link (#fresh?) until its
+    # own worker holds it: written before the move, removed by that worker
+    # once it has the owner lock (Worker#start).
+    def mark(session_id, state_dir:)
+      dir = Session.session_dir(session_id, state_dir: state_dir)
+      FileUtils.mkdir_p(dir)
+      AtomicFile.write(File.join(dir, FILE), JSON.generate({ "pid" => Process.pid, "at" => Time.now.iso8601(3) }))
+    end
+
+    def clear(session_id, state_dir:)
+      FileUtils.rm_f(File.join(Session.session_dir(session_id, state_dir: state_dir), FILE))
+    end
+
+    # Whether a continue is moving delegates to +session_id+ right now: its
+    # marker is there, fresh, and the process that wrote it runs.
+    def fresh?(session_id, state_dir:)
+      file = File.join(Session.session_dir(session_id, state_dir: state_dir), FILE)
+      return false unless File.exist?(file)
+
+      data = JSON.parse(File.read(file))
+      return false if Time.now - Time.iso8601(data["at"].to_s) > STALE
+
+      process_alive?(data["pid"].to_i)
+    rescue JSON::ParserError, ArgumentError, SystemCallError
+      false
+    end
+
+    # Signal 0 only asks whether the process exists.
+    def process_alive?(pid)
+      return false unless pid.positive?
+
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue Errno::EPERM
+      true
+    end
+  end
+end

data/lib/samagotchi/steer_cut_after.rb

@@ -37,18 +37,18 @@ module Samagotchi
     # "steer.cut_after"; nil for the default).
     # @param target [HostRegistry::ModelTarget]
     # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
-    # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
+    # @param models [Hash{String => ModelSettings}, nil] ModelSettings.all (specs)
     # @return [Array(Integer, String|nil)]
     def resolve(target, names:, models: nil)
       value, origin = Config.get_with_origin("steer.cut_after")
       return [value.to_i, ENV_KEY] if origin == :env
 
       models ||= begin
-        ConfigFile.model_settings
+        ModelSettings.all
       rescue StandardError
         {}
       end
-      setting = ConfigFile.model_setting(names, :steer_cut_after, models: models)
+      setting = ModelSettings.find(names, :steer_cut_after, models: models)
       return [setting.value, "models: #{setting.key}"] if setting
 
       host = target.entry.steer_cut_after

data/lib/samagotchi/system_one/recorder.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../log"
+require_relative "recording"
+require_relative "runs"
+
+module Samagotchi
+  module SystemOne
+    # What a turn stage needs to save its System 1 asks as runs: the
+    # Engine's Runs and the session's model as the Engine names it now.
+    # Engine#system_one_recorder builds one fresh at each stage call (never
+    # kept: an outgoing ask after a before_turn hook's model switch names
+    # the new model), on the caller's thread; the stage keeps it only for
+    # that call. NONE is what a stage gets when the Engine couldn't build
+    # one: no runs, every client as it was.
+    #
+    # +runs+ [Runs, nil] where the runs go (Runs#on? false: system_one.runs
+    #   off); nil: NONE
+    # +session_model+ [String, nil] Engine#effective_model_name at the call
+    Recorder = Data.define(:runs, :session_model) do
+      # +client+ (nil for none) saving its asks as +judgment+'s runs. Anything
+      # going wrong here leaves the client as it was: a run is never worth a
+      # judgment. A scratch session's asks aren't saved; a participant's
+      # turn is never judged, so it never comes here.
+      # @param mode [String, nil] the use's mode, for its runs (Recording.wrap)
+      def wrap(client, judgment, session, mode: nil)
+        return client if client.nil? || runs.nil? || session&.scratch
+
+        context = Recording::Context.of(session, session_model: session && session_model)
+        Recording.wrap(client, judgment: judgment, runs: runs, context: context, recorded_mode: mode)
+      rescue StandardError => e
+        Recorder.failed(e)
+        client
+      end
+
+      # Whether runs are saved (an ask whose only use is its run is made
+      # only then: ObjectivesAudit).
+      def saving? = !runs.nil? && runs.on?
+
+      # The one warn for a recording that can't be set up.
+      def self.failed(error)
+        Samagotchi::Log.warn(:system_one, "system_one_recording_failed", error: error.class.name, msg: error.message.to_s[0, 200])
+      end
+    end
+
+    # No recording: the plain client, no runs.
+    Recorder::NONE = Recorder.new(runs: nil, session_model: nil)
+  end
+end

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)
@@ -91,8 +93,10 @@ module Samagotchi
 
     # 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, and its stable part's length (chat).
-    Built = Data.define(:prompt, :memory_index, :notes, :files, :sections, :stable_length)
+    # 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
@@ -110,7 +114,7 @@ module Samagotchi
     # @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]
       cache = @cache
@@ -172,7 +176,8 @@ module Samagotchi
     # 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
@@ -192,12 +197,20 @@ module Samagotchi
       @section_files = []
       @section_plugins = []
       @measured_stable_length = nil
-      prompt = system_prompt_with_index(assist_system_prompt(chat: chat, layers: layers),
-                                        chat: chat, thinking: thinking, layers: layers)
+      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)
+                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
@@ -208,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)
@@ -232,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
@@ -241,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
@@ -332,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)
@@ -340,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")}"
       @measured_stable_length = stable_text.length + 1 if chat
-      with_tail_declarations(prompt, chat: chat, layers: layers)
+      with_tail_declarations(prompt, chat: chat, surface: surface)
     end
 
     # The tools the session's toolkit leaves out, named once right after the
@@ -357,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
@@ -387,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
@@ -406,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/exit_lines.rb

@@ -14,7 +14,7 @@ module Samagotchi
       LATE = "worker not answering in time"
       # An exit the worker agreed to in an empty session. Said before it has
       # left: it checks again once it lets go, and a note or prompt arriving
-      # first keeps the session (SessionManager.discard_left_session).
+      # first keeps the session (WorkerBoot.discard_left_session).
       EMPTY_WORDS = "the session is empty: it will be discarded if nothing arrives before its worker stops."
       EMPTY_EXIT = "Detached; #{EMPTY_WORDS}"
       # Why the worker stayed up after /exit, by the reason it gave.

data/lib/samagotchi/terminal_ui.rb

@@ -44,8 +44,6 @@ module Samagotchi
     # Raised when another process (a worker or another chi) owns the session
     # this run was asked to use.
     class SessionBusy < StandardError; end
-    # --resume with an id that has no saved session.
-    class SessionNotFound < StandardError; end
 
     EMPTY_ANSWER_ERROR = "chi: the model gave an empty answer"
 
@@ -100,9 +98,7 @@ module Samagotchi
       # between the load and the lock that this run would later save over.
       # An unknown id is refused before the claim, which would leave an
       # empty session dir behind.
-      if session_id && !Session.exist?(session_id)
-        raise SessionNotFound, "Session not found: #{session_id}"
-      end
+      raise Session::NotFound, session_id if session_id && !Session.exist?(session_id)
 
       claim_session!(session_id) if session_id
       @resume_session = session_id ? Session.load(session_id) : nil
@@ -434,7 +430,7 @@ module Samagotchi
 
     # A fresh session reaches the disk before its first turn: a tool in that
     # turn reads it from there (delegate loads its parent to start a child,
-    # "Session not found" otherwise).
+    # "no session …" otherwise).
     def save_before_first_turn(session)
       session.save unless Session.exist?(session.id)
     end

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/testing/sessions.rb

@@ -60,7 +60,7 @@ module Samagotchi
       end
 
       def read(id)
-        answer(:read, [id], {}) { raise Plugin::Sessions::Error, "no session #{id}" }
+        answer(:read, [id], {}) { raise Plugin::Sessions::Error, Session::NotFound.new(id).message }
       end
 
       def children(all: false)

data/lib/samagotchi/thinking.rb

@@ -84,7 +84,7 @@ module Samagotchi
     # the default).
     # @param target [HostRegistry::ModelTarget]
     # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
-    # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
+    # @param models [Hash{String => ModelSettings}, nil] ModelSettings.all (specs)
     # @param session [Symbol, nil] the session's own level (Session#thinking)
     # @return [Array(Symbol, String|nil)]
     def resolve(target, names:, models: nil, session: nil)
@@ -94,11 +94,11 @@ module Samagotchi
       return [global, origin == :cli ? "--thinking" : "SAMAGOTCHI_THINKING_LEVEL"] if global && %i[cli env].include?(origin)
 
       models ||= begin
-        ConfigFile.model_settings
+        ModelSettings.all
       rescue StandardError
         {}
       end
-      setting = ConfigFile.model_setting(names, :thinking, models: models)
+      setting = ModelSettings.find(names, :thinking, models: models)
       return [setting.value, "models: #{setting.key}"] if setting
 
       host = target.entry.thinking

data/lib/samagotchi/token_usage.rb

@@ -23,7 +23,7 @@ module Samagotchi
   class TokenUsage < Data.define(:prompt_tokens, :completion_tokens, :cached_tokens, :cache_write_tokens,
                                  :reasoning_tokens, :cost, :predicted_per_second, :prompt_per_second, :predicted_ms, :source)
     CHARS_PER_TOKEN = 4.0
-    # Re-prefilled tokens under this are none (KernelLoop#reprefilled_tokens,
+    # Re-prefilled tokens under this are none (ReprefillMeter#tokens,
     # SessionMetrics): servers count the cache in blocks (OpenAI's 128).
     REPREFILL_MIN_TOKENS = 128
 

data/lib/samagotchi/tool_activity.rb

@@ -5,6 +5,7 @@ require_relative "log"
 require_relative "command_steps"
 require_relative "tool_view"
 require_relative "tools/execute"
+require_relative "tools/registry"
 require_relative "tools/read"
 require_relative "tools/write"
 require_relative "tools/memory"
@@ -58,11 +59,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 +360,10 @@ 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, which a tool's entry is
+    # looked up in, for a preview that reads it (call_tool's); nil outside a
+    # turn (+registry+'s entry then).
+    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 +457,8 @@ 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(surface ? surface.registered[tool_name.to_s] : registry_entry(registry, tool_name), call,
+                        surface)
       end
     end
 
@@ -471,14 +476,17 @@ module Samagotchi
     # key="value" (the parsers' args:, which a registry-less reader such as
     # 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)
+    # (the reminder tools). A missing surface (Tools::MissingSurface) is
+    # raised, never taken as a failing preview.
+    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 Tools::MissingSurface
+          raise
         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

@@ -2,7 +2,7 @@
 
 require "json"
 require_relative "tools/args"
-require_relative "llm_context_strategy"
+require_relative "config"
 require_relative "tools/memory"
 
 module Samagotchi
@@ -482,7 +482,7 @@ module Samagotchi
     # (Tools::Registry's layer gate), so it is not in TOOL_SCHEMAS, which
     # every turn declares. Its description carries llm_context.policy
     # (#forget_outputs_schema); this one the default's.
-    FORGET_OUTPUTS_POLICY = LLMContextStrategy::DEFAULT_POLICY
+    FORGET_OUTPUTS_POLICY = Config::DEFAULT_LLM_CONTEXT_POLICY
     FORGET_OUTPUTS_DESCRIPTION = "Forget tool outputs you no longer need, to free context. Every tool output starts " \
                                  "with an id like [#t42]: list ids to forget, and each output is replaced in place by " \
                                  "a stub with your note (the call stays). %<policy>s\n" \
@@ -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_output_cut.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "config"
 require_relative "tool_output_files"
 
 module Samagotchi
@@ -28,6 +29,22 @@ module Samagotchi
   # task's log, the child's reply in its output/ folder), which the tool
   # gave with its text (Tools::RefText) and the gap line names.
   module ToolOutputCut
+    # The per-output cap with nothing set (max_tool_output_chars).
+    DEFAULT_MAX_CHARS = 10_000
+
+    # The per-output cap both loops cut tool outputs to (and the emitted
+    # tool call events carry): an explicit +override+ wins, then
+    # max_tool_output_chars (Config). A non-positive value falls back to
+    # DEFAULT_MAX_CHARS (there is intentionally no "unlimited": live UIs get
+    # a bounded `output:` plus a truthful `output_truncated:` flag). The one
+    # exception is memory_read, which ToolRunner leaves out of this cap
+    # (memory.read_max_chars, 0: no fixed cap; a memory is read whole).
+    # @return [Integer]
+    def self.max_chars(override)
+      parsed = (override || Config.get("max_tool_output_chars")).to_i
+      parsed.positive? ? parsed : DEFAULT_MAX_CHARS
+    end
+
     POLICIES = { "execute" => :head_tail_file, "task_wait" => :head_tail_ref, "delegate" => :head_tail_ref,
                  "delegate_result" => :head_tail_ref }.freeze
 

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