samagotchi 0.69.0 → 0.70.0

data/lib/samagotchi/tool_output_cut.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+require_relative "tool_output_files"
+
+module Samagotchi
+  # How ToolRunner cuts a tool's output that is longer than
+  # max_tool_output_chars, by the tool's policy (POLICIES, by its built-in
+  # name; any other tool gets :head).
+  #
+  # :head keeps the first chars and ends with head_line ("[cut: N of M
+  # chars; read it in parts]"): read (which has line ranges) and every tool
+  # with no policy of its own.
+  #
+  # :head_tail_file (execute) keeps a short head and a long tail, whole
+  # lines, with one gap line between them, and saves the whole output
+  # (ToolOutputFiles, through the caller's +save+): a test run's verdict and
+  # an error are at the end. The gap line names the saved file and the lines
+  # left out of it, so the model reads or rg's it instead of running the
+  # command again. execute's stdout and stderr are cut each on its own
+  # (stdout gets about two thirds of the room), its exit line always kept.
+  # The cut text still fits the cap, and comes from the content alone (no
+  # clock): the same output gives the same text.
+  #
+  # :head_tail_ref (task_wait, delegate, delegate_result) cuts the same
+  # way, as one block, and saves nothing: the whole is already in a file (a
+  # 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
+    POLICIES = { "execute" => :head_tail_file, "task_wait" => :head_tail_ref, "delegate" => :head_tail_ref,
+                 "delegate_result" => :head_tail_ref }.freeze
+
+    # What a :head_tail_ref tool's file holds, for its gap line.
+    REF_WHAT = { "task_wait" => "the task's whole output", "delegate" => "the child's whole reply",
+                 "delegate_result" => "the child's whole reply" }.freeze
+
+    # A head cut's last line (head_line), as LLMContextStale recognizes a
+    # partial read by it. Kept in sync with head_line by its spec.
+    HEAD_CUT = /\[cut: \d+ of \d+ chars; read it in parts\]\z/
+
+    # The head's chars at most (execute.cut_head_chars): never more than a
+    # quarter of the room; the tail gets the rest.
+    HEAD_CHARS = 1000
+    # A tail shorter than this isn't worth it: the cap is too small, and
+    # the output gets the head cut.
+    MIN_TAIL = 200
+
+    # An execute that didn't finish: stopped, killed at the limit or
+    # handed over (its result starts with an "Error:" or a "Still running"
+    # line after the lead), or with no exit line last.
+    UNFINISHED = /\A(?:ran as: [^\n]*\n)?\[execute\]\n(?:Error: |Still running at the )/
+
+    # The marks of a text that is already a head-and-tail preview (execute's
+    # own above execute.truncate_at_bytes): its saved copy isn't the whole
+    # output.
+    PREVIEW_MARK = "[TRUNCATED_PREVIEW_HEAD]"
+    # execute's blocks (Tools::Execute#call): stdout, stderr, then the exit
+    # line last (a hint in brackets may follow it). A killed or handed-over
+    # command has none: its output isn't all there is.
+    STDOUT_LABEL = "\nstdout:\n"
+    STDERR_LABEL = "\nstderr:\n"
+    EXIT_LINE = /\nexit: -?\d+[^\n]*(?:\n\([^\n]*\))?\z/
+
+    # The share of the room stdout gets when both blocks are cut.
+    STDOUT_SHARE = Rational(2, 3)
+
+    # A cut part: [from, length] of the output.
+    Block = Data.define(:from, :length) do
+      def to = from + length
+    end
+
+    module_function
+
+    # @param tool [String, nil] the call's tool name
+    # @return [Symbol] its policy
+    def policy(tool) = POLICIES.fetch(tool.to_s, :head)
+
+    # +output+ cut to +cap+ chars by +tool+'s policy.
+    # @param save [#call, nil] (text, dry:) → ToolOutputFiles::Saved, or a
+    #   String saying why it wasn't saved ("no session", "Errno::ENOSPC");
+    #   dry: true only says where it would go. It writes only once the
+    #   head-and-tail cut is known to fit the cap with that file's gap
+    #   line: a cut that falls back to the head cut saves nothing.
+    # @param head_chars [Integer] execute.cut_head_chars
+    # @return [Array(String, Object)] the text the model gets, and what
+    #   +save+ returned (nil when it wasn't called)
+    # @param ref [String, nil] :head_tail_ref: the file the whole text is in
+    # @param ref_stderr [String, nil] :head_tail_ref: its stderr's file, if apart
+    def apply(output, cap:, tool:, save: nil, ref: nil, ref_stderr: nil, head_chars: HEAD_CHARS)
+      kind = policy(tool)
+      return [head(output, cap), nil] if kind == :head || cap < MIN_TAIL * 3
+
+      if kind == :head_tail_ref
+        text = head_tail(output, cap: cap, blocks: [Block.new(from: 0, length: output.length)], head_chars: head_chars,
+                                 gap: RefGap.new(output, ref, REF_WHAT.fetch(tool.to_s, "the whole output"),
+                                                 stderr: ref_stderr))
+        return [text || head(output, cap), nil]
+      end
+
+      blocks = execute_blocks(output)
+      planned = save ? save.call(output, dry: true) : "no session"
+      text = head_tail(output, cap: cap, blocks: blocks, head_chars: head_chars, gap: FileGap.new(output, planned))
+      return [head(output, cap), nil] unless text
+      return [text, planned] unless planned.is_a?(ToolOutputFiles::Saved)
+
+      saved = save.call(output)
+      return [text, saved] if saved.is_a?(ToolOutputFiles::Saved)
+
+      # The write failed: the line says so instead, if that still fits.
+      text = head_tail(output, cap: cap, blocks: blocks, head_chars: head_chars, gap: FileGap.new(output, saved))
+      [text || head(output, cap), text ? saved : nil]
+    end
+
+    def unfinished?(output) = output.match?(UNFINISHED) || !output.match?(EXIT_LINE)
+
+    # +output+ as a web row keeps it, at most +cap+ chars (a reload's
+    # MessageParts, the Bridge's snapshot): a read's head (its view numbers
+    # the lines from the first), any other tool's head and tail with a gap
+    # line, as the model's cut keeps a test run's verdict and exit line.
+    def preview(output, cap:, tool:)
+      return output if output.length <= cap
+      return output[0, cap] if tool.to_s == "read"
+
+      head_tail(output, cap: cap, blocks: [Block.new(from: 0, length: output.length)], head_chars: HEAD_CHARS,
+                                  gap: RefGap.new(output, nil, nil)) || output[0, cap]
+    end
+
+    # +output+ cut to +cap+ chars, the cut line included: the model knows
+    # what it didn't get. A cap smaller than the line keeps +cap+ chars and
+    # the line goes past it.
+    def head(output, cap)
+      keep = cap - head_line(cap, output.length).length
+      keep = cap unless keep.positive?
+      "#{output[0, keep]}#{head_line(keep, output.length)}"
+    end
+
+    def head_line(kept, total)
+      "\n[cut: #{kept} of #{total} chars; read it in parts]"
+    end
+
+    # +output+ with each of +blocks+ that doesn't fit its share of the room
+    # cut to its head and tail, a gap line between them (the first cut's
+    # line +gap+.line, the next ones' +gap+.short). nil when the cap leaves
+    # too little room.
+    def head_tail(output, cap:, blocks:, head_chars:, gap:)
+      fixed = output.length - blocks.sum(&:length)
+      # Room for the gap lines (their longest numbers) and a newline each.
+      room = cap - fixed - (gap.line_max.length + 2) - (blocks.size > 1 ? gap.short_max.length + 2 : 0)
+      shares = shares(blocks.map(&:length), room)
+      return nil unless shares
+
+      text = +""
+      at = 0
+      first = true
+      blocks.zip(shares).each do |block, share|
+        text << output[at...block.from]
+        at = block.to
+        body = output[block.from, block.length]
+        if body.length <= share
+          text << body
+          next
+        end
+
+        shown = cut_block(body, share, head_chars)
+        return nil unless shown
+
+        head_part, tail_part = shown
+        left_out = Block.new(from: block.from + head_part.length, length: body.length - head_part.length - tail_part.length)
+        text << head_part
+        text << "\n" unless head_part.end_with?("\n") || head_part.empty?
+        text << (first ? gap.line(left_out) : gap.short(left_out)) << "\n" << tail_part
+        first = false
+      end
+      text << output[at..]
+      text.length <= cap ? text : nil
+    end
+
+    # The room each block gets: stdout STDOUT_SHARE when both need cutting,
+    # a block that needs less gives the rest to the other. nil when there
+    # isn't room for a useful tail.
+    def shares(lengths, room)
+      return nil if room < MIN_TAIL
+      return [room] if lengths.size == 1
+
+      first = (room * STDOUT_SHARE).floor
+      second = room - first
+      if lengths[1] < second
+        [room - lengths[1], lengths[1]]
+      elsif lengths[0] < first
+        [lengths[0], room - lengths[0]]
+      else
+        [first, second]
+      end
+    end
+
+    # +body+'s head and tail within +share+ chars, each snapped to whole
+    # lines when that keeps at least half of it. nil when the tail would
+    # be shorter than MIN_TAIL.
+    def cut_block(body, share, head_chars)
+      head_size = [head_chars, share / 4].min
+      tail_size = share - head_size
+      return nil if tail_size < MIN_TAIL
+
+      head_part = body[0, head_size]
+      newline = head_part.rindex("\n")
+      head_part = head_part[0, newline + 1] if newline && newline + 1 >= head_size / 2
+      tail_part = body[-tail_size..]
+      newline = tail_part.index("\n")
+      tail_part = tail_part[(newline + 1)..] if newline && tail_part.length - newline - 1 >= tail_size / 2
+      [head_part, tail_part]
+    end
+
+    # execute's stdout and stderr bodies, each cut on its own; any other
+    # text (no "stdout:"/"stderr:" block: an error, a hand-over) is one.
+    def execute_blocks(output)
+      ends = output.match(EXIT_LINE)&.begin(0) || output.length
+      stdout_at = output.index(STDOUT_LABEL)
+      stderr_at = output.rindex(STDERR_LABEL, ends - STDERR_LABEL.length)
+      stderr_at = nil if stderr_at && stdout_at && stderr_at < stdout_at
+      blocks = []
+      if stdout_at
+        from = stdout_at + STDOUT_LABEL.length
+        blocks << Block.new(from: from, length: [(stderr_at || ends) - from, 0].max)
+      end
+      blocks << Block.new(from: stderr_at + STDERR_LABEL.length, length: ends - stderr_at - STDERR_LABEL.length) if stderr_at
+      blocks.empty? ? [Block.new(from: 0, length: output.length)] : blocks
+    end
+
+    # The gap line of a :head_tail_ref cut: the file the whole text is in.
+    class RefGap
+      def initialize(output, ref, what, stderr: nil)
+        @output = output
+        @ref = ref.to_s
+        @what = what
+        @stderr = stderr.to_s
+      end
+
+      def line(left_out)
+        also = @stderr.empty? ? "" : " (its stderr in #{@stderr})"
+        where = @ref.empty? ? "" : "; #{@what} is in #{@ref}#{also}: read it with start_line/end_line or rg it"
+        "[cut: #{left_out.length} of #{@output.length} chars not shown#{where}]"
+      end
+
+      def short(left_out) = "[cut: #{left_out.length} chars not shown]"
+      def line_max = line(Block.new(from: 0, length: @output.length))
+      def short_max = short(Block.new(from: 0, length: @output.length))
+    end
+
+    # The gap lines of a :head_tail_file cut: where the whole output is
+    # saved, and which of its lines the cut left out.
+    class FileGap
+      # @param saved [ToolOutputFiles::Saved, String] the saved file, or
+      #   why there is none
+      def initialize(output, saved)
+        @output = output
+        @saved = saved.is_a?(String) ? nil : saved
+        @reason = saved.is_a?(String) ? saved : nil
+      end
+
+      # The first cut's line.
+      def line(left_out)
+        return "[cut: #{left_out.length} of #{@output.length} chars not shown; #{unsaved_note}]" unless @saved
+
+        "[cut: #{lines_text(left_out)} of the saved file not shown (#{left_out.length} of #{@output.length} chars); " \
+          "#{saved_note}]"
+      end
+
+      # A further cut's line, the file named by the first.
+      def short(left_out)
+        return "[cut: #{left_out.length} chars not shown]" unless @saved
+
+        "[cut: #{lines_text(left_out)} of the saved file not shown (#{left_out.length} chars)]"
+      end
+
+      # The longest line and short line it can write (budgeting).
+      def line_max = line(widest)
+      def short_max = short(widest)
+
+      private
+
+      def widest = Block.new(from: 0, length: @output.length)
+
+      def lines_text(left_out)
+        return "lines #{lines_total}-#{lines_total}" if left_out.from.zero? && left_out.length == @output.length
+
+        first = @output[0, left_out.from].count("\n") + 1
+        last = @output[0, left_out.to].count("\n")
+        last += 1 unless left_out.to.zero? || @output[left_out.to - 1] == "\n"
+        "lines #{first}-#{[last, first].max}"
+      end
+
+      def lines_total = @saved.lines
+
+      def where = "#{@saved.path} (#{@saved.bytes} bytes, #{@saved.lines} lines)"
+
+      def saved_note
+        if @output.include?(PREVIEW_MARK)
+          "this preview is saved in #{where}; the full output wasn't kept: read the preview with " \
+            "start_line/end_line or rg it"
+        elsif ToolOutputCut.unfinished?(@output)
+          "the output it printed is saved in #{where}: read it with start_line/end_line or rg it"
+        else
+          "the whole output is saved in #{where}: read it with start_line/end_line or rg it; don't rerun the command"
+        end
+      end
+
+      def unsaved_note
+        "the whole output wasn't saved (#{@reason}); to look past this, rerun with the output sent to a file " \
+          "(cmd > /tmp/out.txt 2>&1) and read that"
+      end
+    end
+  end
+end

data/lib/samagotchi/tool_output_files.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require_relative "atomic_file"
+
+module Samagotchi
+  # The whole output of a tool call ToolRunner cut (ToolOutputCut's
+  # :head_tail_file), saved in the session's folder, tool_output/
+  # (sessions/<id>/tool_output/; not output/, the session's reply outbox),
+  # so the model reads or rg's it instead of running the command again.
+  #
+  # The name comes from the content (<tool>-<sha256[0,12]>.txt): the same
+  # output gives the same path, so the cut text is the same each time
+  # (loop-guard's repeat check, the prompt cache). The files go with the
+  # session folder; a session keeps its newest MAX_FILES.
+  module ToolOutputFiles
+    DIR = "tool_output"
+    MAX_FILES = 50
+
+    # Where a saved output is, and its size.
+    Saved = Data.define(:path, :bytes, :lines)
+
+    module_function
+
+    # @param session_dir [String] the session's folder (Session.session_dir)
+    # @param text [String] the output, saved byte for byte
+    # @param tool [String] the tool's name, the file name's start
+    # @return [Saved]
+    # @raise [SystemCallError] when it can't be written
+    def save(session_dir, text, tool:)
+      path = planned(session_dir, text, tool: tool).path
+      dir = File.dirname(path)
+      FileUtils.mkdir_p(dir)
+      # Already there (the same output again): newest now, not rewritten.
+      # An empty one (cut short) is written again.
+      if File.size?(path)
+        FileUtils.touch(path)
+      else
+        AtomicFile.write(path, text)
+      end
+      prune(dir)
+      planned(session_dir, text, tool: tool)
+    end
+
+    # Where #save would put +text+, and its size, with nothing written: the
+    # cut checks its gap line fits before anything is saved.
+    # @return [Saved]
+    def planned(session_dir, text, tool:)
+      path = File.join(session_dir, DIR, "#{file_tool(tool)}-#{Digest::SHA256.hexdigest(text)[0, 12]}.txt")
+      Saved.new(path: path, bytes: text.bytesize, lines: line_count(text))
+    end
+
+    # The lines a text has, a last line with no newline counted.
+    def line_count(text)
+      text.count("\n") + (text.empty? || text.end_with?("\n") ? 0 : 1)
+    end
+
+    # A tool name safe in a file name (a plugin's or an MCP tool's).
+    def file_tool(tool)
+      name = tool.to_s.downcase.gsub(/[^a-z0-9_-]/, "_")
+      name.empty? ? "tool" : name
+    end
+
+    # Keeps the newest MAX_FILES files of +dir+, by mtime.
+    def prune(dir)
+      files = Dir.glob(File.join(dir, "*.txt"))
+      return if files.size <= MAX_FILES
+
+      files.sort_by { |f| [-File.mtime(f).to_f, f] }.drop(MAX_FILES).each { |f| FileUtils.rm_f(f) }
+    end
+  end
+end

data/lib/samagotchi/tool_runner.rb

@@ -7,6 +7,9 @@ require_relative "guardrails"
 require_relative "vision_context"
 require_relative "log"
 require_relative "edit_preview"
+require_relative "tool_output_cut"
+require_relative "tool_output_files"
+require_relative "tools/output_guardrails"
 require_relative "tools/tool_path"
 require_relative "memory_bundle/index_sync"
 require_relative "memory_bundle/index_size"
@@ -16,8 +19,8 @@ module Samagotchi
   # tool_call_completed events, the guardrail gate (before_tool_call hooks
   # and their veto), dispatch through KernelLoop, the after_tool_call hook
   # and the output cap. Both loops feed the model `capped_output:` (cut to
-  # the cap with a "[cut: N of M chars …]" line), the text the event and
-  # the hook get too.
+  # the cap by the tool's ToolOutputCut policy, with a "[cut: …]" line),
+  # the text the event and the hook get too.
   class ToolRunner
     # More images in one result are left out, each with a line (a tool
     # that returns many screenshots can't flood the context).
@@ -38,6 +41,7 @@ module Samagotchi
 
     # @param call_index [Integer] 1-based position of the call in its batch
     # @return [Hash] output:, capped_output:, truncated:, activity:,
+    #   output_file: (the saved whole output of a cut execute result),
     #   images: (refs) when the tool returned images the model gets to see, and
     #   shown_params: the params line the live row showed, and shown_label:
     #   its label ("chrome: screenshot"), only for a tool that isn't built in
@@ -109,7 +113,8 @@ module Samagotchi
         output = "#{changed}\n#{output}"
       end
       truncated = !max_tool_output_chars.nil? && output.length > max_tool_output_chars
-      capped = truncated ? cut(output, max_tool_output_chars) : output
+      capped, saved = truncated ? cut(call, output, max_tool_output_chars, result) : output
+      output_file = saved.path if saved.is_a?(ToolOutputFiles::Saved)
 
       # The call's outcome as its activity line has it (worked out from the
       # full output: ok, error, blocked, stopped); a dispatcher that raised
@@ -120,6 +125,7 @@ module Samagotchi
       completed[:images] = images if images&.any?
       completed[:diff] = diff if diff
       completed[:waited_ms] = waited_ms if waited_ms
+      completed[:output_file] = output_file if output_file
       # Also here: a UI that missed the start (a replay gap) builds its row
       # from this event (its title is in the activity).
       completed.merge!(fields.slice(*ToolRowFields::EVENT_KEYS))
@@ -135,22 +141,50 @@ module Samagotchi
       run[:shown_label] = label if label
       run[:refs] = refs unless refs.empty?
       run[:diff] = diff if diff
+      run[:output_file] = output_file if output_file
       run
     end
 
     private
 
-    # +output+ cut to +cap+ chars, the cut line included: the model knows
-    # what it didn't get. A cap smaller than the line keeps +cap+ chars and
-    # the line goes past it.
-    def cut(output, cap)
-      keep = cap - cut_line(cap, output.length).length
-      keep = cap unless keep.positive?
-      "#{output[0, keep]}#{cut_line(keep, output.length)}"
+    # +output+ cut to +cap+ by its tool's policy (ToolOutputCut); an
+    # execute result keeps its tail too, its whole output saved in the
+    # session's folder.
+    # @param result [Hash] the dispatch's: its ref_path is the file the
+    #   whole text is in (a task's log, a child's reply: Tools::RefText),
+    #   for task_wait and delegate; ref_stderr_path, a task's stderr log
+    # @return [Array(String, Object)] the text, and the saved file (or why
+    #   there is none) when it was cut that way
+    def cut(call, output, cap, result)
+      ToolOutputCut.apply(output, cap: cap, tool: call[:name], save: ->(text, dry: false) { save_output(call, text, dry: dry) },
+                                  ref: result[:ref_path], ref_stderr: result[:ref_stderr_path],
+                                  head_chars: Tools::OutputGuardrails.config_positive_int("execute.cut_head_chars",
+                                                                                          ToolOutputCut::HEAD_CHARS))
     end
 
-    def cut_line(kept, total)
-      "\n[cut: #{kept} of #{total} chars; read it in parts]"
+    # The whole output in the session's tool_output folder
+    # (ToolOutputFiles), or why it isn't saved: no session (a bare kernel)
+    # or the error's class. Never fails the call. +dry+: where it would go,
+    # nothing written (ToolOutputFiles.planned).
+    # @return [ToolOutputFiles::Saved, String]
+    def save_output(call, text, dry: false)
+      dir = session_dir
+      return "no session" if dir.to_s.empty?
+      return ToolOutputFiles.planned(dir, text, tool: call[:name]) if dry
+
+      ToolOutputFiles.save(dir, text, tool: call[:name])
+    rescue SystemCallError => e
+      Log.warn(:turn, "tool_output_save_failed", tool: call[:name], error: e.class.name)
+      e.class.name
+    end
+
+    # The session's folder (KernelLoop#session_dir), nil for a bare kernel
+    # or a lookup that failed.
+    def session_dir
+      @kernel.respond_to?(:session_dir) ? @kernel.session_dir&.call : nil
+    rescue StandardError => e
+      Log.warn(:turn, "tool_output_save_failed", error: e.class.name)
+      nil
     end
 
     # edit/write only: the file just before the call runs. The row diffs it

data/lib/samagotchi/tools/delegate.rb

@@ -66,7 +66,10 @@ module Samagotchi
         return child_id if child_id.start_with?("Error:")
 
         note = warning ? "Warning: #{warning}\n" : ""
-        return note + DelegateWait.call(child_id, peers: peers, timeout: timeout) if wait
+        if wait
+          result = DelegateWait.call(child_id, peers: peers, timeout: timeout)
+          return RefText.wrap(note + result, result.respond_to?(:ref_path) ? result.ref_path : nil)
+        end
 
         started = session.to_s.strip.empty? ? "Started a delegate session" : "Sent the follow-up to delegate #{child_id[0, 8]}"
         "#{note}session: #{child_id}\nstatus: running\n#{started}; #{running_hint(peers)} " \

data/lib/samagotchi/tools/delegate_wait.rb

@@ -7,6 +7,7 @@ require_relative "output_guardrails"
 require_relative "peers"
 require_relative "delegate_relay"
 require_relative "delegate_cursor"
+require_relative "ref_text"
 
 module Samagotchi
   # Loaded on first use: child_reports requires this file (a circular
@@ -78,7 +79,8 @@ module Samagotchi
           unless wait.status == :waiting_for_answer && DelegateRelay.relayable?(relay, wait.question)
             outcomes.concat(relayed_outcomes.delete(key) || [])
             advance(peers.session_id, child_id, wait, state_dir: sd)
-            return with_outcomes(finish(wait, child_id, timeout: timeout, reports: reports), outcomes)
+            text = with_outcomes(finish(wait, child_id, timeout: timeout, reports: reports), outcomes)
+            return RefText.wrap(text, reply_path(child_id, wait, state_dir: sd))
           end
 
           outcome = DelegateRelay.call(child_id, wait.question, relay: relay, state_dir: sd, more: others&.count.to_i)
@@ -104,6 +106,15 @@ module Samagotchi
                                   })
       end
 
+      # The child's reply file a :done wait read (its output/ file), which
+      # ToolRunner's cut of a long reply names (ToolOutputCut's
+      # :head_tail_ref); nil for any other outcome.
+      def reply_path(child_id, wait, state_dir:)
+        return nil unless wait.status == :done && wait.file
+
+        File.join(ReplyWait.reply_dir(child_id, state_dir: state_dir), wait.file)
+      end
+
       # The relayed approvals' outcome lines, after the status line.
       def with_outcomes(text, outcomes)
         return text if outcomes.empty?

data/lib/samagotchi/tools/ref_text.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Tools
+    # A tool's text that shows part of a file kept elsewhere in whole: a
+    # task's log (task_wait's output tail), a child's reply file (delegate,
+    # delegate_result). It is the text itself (a String), like
+    # Plugin::ToolResult; #ref_path is the file, which ToolRunner's cut
+    # names when the text is longer than max_tool_output_chars
+    # (ToolOutputCut's :head_tail_ref), instead of saving a copy;
+    # #stderr_path, a handed-over execute's stderr log, the cut names too.
+    class RefText < String
+      attr_reader :ref_path, :stderr_path
+
+      def initialize(text, ref_path, stderr_path: nil)
+        @ref_path = ref_path
+        @stderr_path = stderr_path.to_s.empty? ? nil : stderr_path
+        super(text.to_s)
+      end
+
+      # +text+ as a RefText of +ref_path+; +text+ as it is with no path.
+      def self.wrap(text, ref_path, stderr_path: nil)
+        ref_path.to_s.empty? ? text : new(text, ref_path, stderr_path: stderr_path)
+      end
+    end
+  end
+end

data/lib/samagotchi/tools/task_wait.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "task_runtime"
+require_relative "ref_text"
 
 module Samagotchi
   module Tools
@@ -121,7 +122,9 @@ module Samagotchi
         lines << output_tail.rstrip unless output_tail.empty?
         stderr_tail = stderr_tail(record, tail_lines)
         lines.concat(["stderr_tail:", stderr_tail.rstrip]) unless stderr_tail.empty?
-        lines.join("\n")
+        # The whole log is at output_path (stderr at stderr_path): a cut of
+        # this text names them.
+        RefText.wrap(lines.join("\n"), record.output_path, stderr_path: record.stderr_path)
       end
       private_class_method :format_response
 

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.69.0"
+  VERSION = "0.70.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

data/lib/samagotchi/web/message_parts.rb

@@ -10,6 +10,7 @@ require_relative "../image_store"
 require_relative "../llm_context_edit"
 require_relative "../token_usage"
 require_relative "../row_refs"
+require_relative "../tool_output_cut"
 
 module Samagotchi
   module Web
@@ -50,7 +51,8 @@ module Samagotchi
       # so an output that holds the joiner itself stays whole.
       JOINER_BEFORE_TAG = /\n\n---\n\n(?=\[)/
       # The row shows 300 chars and the rest on hover; a read of a big file
-      # would otherwise ride along with every reload.
+      # would otherwise ride along with every reload. A longer one keeps its
+      # head and tail (ToolOutputCut.preview).
       OUTPUT_MAX = 2000
 
       QWEN_THINK = %r{<think>(.*?)</think>}m
@@ -246,7 +248,7 @@ module Samagotchi
         part.merge!(ToolRowFields.for(name, call, cwd: cwd))
         part[:label] = label if label.is_a?(String) && !label.empty?
         unless output.nil?
-          part[:output] = output.length > OUTPUT_MAX ? output[0, OUTPUT_MAX] : output
+          part[:output] = ToolOutputCut.preview(output, cap: OUTPUT_MAX, tool: name)
           part[:output_truncated] = true if output.length > OUTPUT_MAX
         end
         shots = Array(images).select { |image| image.is_a?(Hash) }

data/lib/samagotchi/worker.rb

@@ -496,13 +496,13 @@ module Samagotchi
     # turn from context:<name> whose first message is the wake note already
     # in the conversation (named by +turn_id+), on the same rules as a
     # delegate report's wake turn: it counts toward session.max_wakes (a
-    # peer's answer toward context.peer_turns too), and a failure goes back
+    # peer's answer toward context.peer_turns too, unless it agrees), and a failure goes back
     # to before the turn (the note stays, as a plain one:
     # WorkerInbound#unmark_wake) and pauses wakes until a human's input.
     # +context_wake+: a WorkerInbound::ContextWake.
     def run_context_wake_turn(context_wake)
       name = context_wake.name
-      Log.info(:worker, "context_wake_turn", name: name, in_a_row: @wakes.count!(peer: context_wake.peer?))
+      Log.info(:worker, "context_wake_turn", name: name, in_a_row: @wakes.count!(peer: context_wake.peer_turn?))
       @turn_flow.before_prompt_turn
       run_engine_turn(nil, continue: true, origin: context_wake.origin,
                            id: context_wake.turn_id, max_iterations: IterationLimit.for) do |result, error|

data/lib/samagotchi/worker_inbound.rb

@@ -47,6 +47,9 @@ module Samagotchi
       def name = delivery.name
       # For a peer agent's answer (its own budget, WorkerWakes#peer_open?).
       def peer? = !delivery.peer.nil?
+      # Whether the wake counts toward context.peer_turns: a peer's answer
+      # that agrees closes the round and counts toward session.max_wakes only.
+      def peer_turn? = peer? && !delivery.agreed
       def origin = { client_id: "#{ClientId::CONTEXT_PREFIX}#{name}" }
     end