samagotchi 0.69.0 → 0.71.0

data/lib/samagotchi/plugin/peer.rb

@@ -12,7 +12,7 @@ module Samagotchi
     # docs/plugins.md): a live link between a chi session and another agent's
     # session the user works with. The peer pairs (its chi-peer skill,
     # scripts/pair): it attaches the `<peer>-inbox` context, whose hint says
-    # where to send (a subclass's #check_hint!), and `<peer>-review`, where
+    # where to send (a subclass's #check_hint!), and `<peer>-outbox`, where
     # its answers come back as pushes that wake chi.
     #
     # The `<peer>_send` tool sends a part of the work (a plan step, a diff, a
@@ -40,7 +40,7 @@ module Samagotchi
     # `From your thinking:` label.
     #
     # A subclass (the bundle's Plugin) sets the strings, as constants:
-    # INBOX, REVIEW ("<peer>-inbox", "-review"), BUNDLE, NAME (the peer, as
+    # INBOX, OUTBOX ("<peer>-inbox", "-outbox"), BUNDLE, NAME (the peer, as
     # the model and user call it: "Claude"), APP (its product: "Claude
     # Code"), COMMAND ("/claude"), TOOL, TOOL_DESCRIPTION, TOOL_PARAMS,
     # USAGE, STATUS_CARD, SKILL_CARD, CHECKED_ON and SCRIPTS_DIRS (beside the
@@ -90,9 +90,9 @@ module Samagotchi
         end
         # A chi without chi.annotation (before 0.66) loads the bundle without the pill.
         chi.annotation "Confirm with #{peer::NAME}", command: "#{peer::COMMAND} validate" if chi.respond_to?(:annotation)
-        # The review source is the peer's answers: its own wake budget and
+        # The outbox source is the peer's answers: its own wake budget and
         # line (context.peer_turns). A chi before 0.67 has no peer_source.
-        chi.peer_source peer::REVIEW, label: peer::NAME if chi.respond_to?(:peer_source)
+        chi.peer_source peer::OUTBOX, label: peer::NAME if chi.respond_to?(:peer_source)
         chi.on(:before_turn) do |event|
           @lock.synchronize { @before_turn = Array(event[:messages]) }
         end
@@ -172,7 +172,7 @@ module Samagotchi
 
       def send_text(ctx, kind, text)
         "#{deliver(ctx, kind: kind, title: text_title(text), text: text)}; #{self.class::NAME}'s answer comes as the " \
-          "#{self.class::REVIEW} context"
+          "#{self.class::OUTBOX} context"
       rescue SendError => e
         "#{self.class::COMMAND}: #{e.message}"
       end
@@ -240,7 +240,7 @@ module Samagotchi
         peer = self.class
         id = ctx.session_id
         sources = id ? sources(ctx) : []
-        inbox, review = [peer::INBOX, peer::REVIEW].map { |name| sources.find { |source| source[:name] == name } }
+        inbox, outbox = [peer::INBOX, peer::OUTBOX].map { |name| sources.find { |source| source[:name] == name } }
         hint = inbox && inbox[:hint].to_s.strip
         paired = !(hint.nil? || hint.empty?)
         lines = if paired
@@ -250,7 +250,8 @@ module Samagotchi
                    "#{peer::NAME} \"pair with chi #{id.to_s[0, 8]}\"."]
                 end
         lines << "last send: #{last_send_line(ctx, id)}" if id && last_send(ctx, id)
-        lines << "last answer (#{peer::REVIEW}): #{review_line(review)}" if review
+        lines << "last answer (#{peer::OUTBOX}): #{outbox_line(outbox)}" if outbox
+        lines << "skill: **differs from this bundle's**: #{peer::COMMAND} install-skill (Replace), then pair again" if skill_differs?(ctx)
         lines << transport_line
         ctx.card(id: peer::STATUS_CARD, title: "#{peer::BUNDLE}: #{paired ? "paired" : "not paired"}",
                  body: lines.join("\n\n"), actions: [{ label: "Refresh", command: peer::COMMAND },
@@ -271,10 +272,10 @@ module Samagotchi
         "#{ago(sent["at"])} · #{sent["kind"]} · #{sent["title"]} (#{sent["chars"]} chars, #{where})"
       end
 
-      def review_line(review)
-        return "none yet" unless review[:fetched_at]
+      def outbox_line(outbox)
+        return "none yet" unless outbox[:fetched_at]
 
-        [review[:summary], ago(review[:fetched_at])].compact.join(" · ")
+        [outbox[:summary], ago(outbox[:fetched_at])].compact.join(" · ")
       end
 
       def ago(stamp)
@@ -291,14 +292,32 @@ module Samagotchi
       # /<peer> install-skill [--yes]
       def install_skill(ctx, yes:)
         peer = self.class
-        source = peer::SCRIPTS_DIRS.map { |dir| File.join(dir, SKILL_FILE) }.find { |path| File.file?(path) }
-        return "#{peer::COMMAND} install-skill: this bundle has no scripts/#{SKILL_FILE}; reinstall it (chi bundle install #{peer::BUNDLE} --force)" unless source
+        target, text = skill_target_and_text(ctx)
+        return "#{peer::COMMAND} install-skill: this bundle has no scripts/#{SKILL_FILE}; reinstall it (chi bundle install #{peer::BUNDLE} --force)" unless text
+
+        yes ? write_skill(ctx, target, text) : skill_card(ctx, target, text)
+      end
+
+      # Where install-skill writes the peer's skill and what it writes:
+      # [target, text]; the text nil when the bundle has no skill file.
+      def skill_target_and_text(ctx)
+        target = File.join(peer_dir, "skills", "chi-peer", "SKILL.md")
+        source = self.class::SCRIPTS_DIRS.map { |dir| File.join(dir, SKILL_FILE) }.find { |path| File.file?(path) }
+        return [target, nil] unless source
 
         substitutions = { PAIR_PLACEHOLDER => File.join(File.dirname(source), "pair"),
                           PAYLOADS_PLACEHOLDER => tilde(ctx.data_dir) }.merge(skill_substitutions(ctx))
-        text = substitutions.reduce(File.read(source)) { |skill, (placeholder, value)| skill.gsub(placeholder, value) }
-        target = File.join(peer_dir, "skills", "chi-peer", "SKILL.md")
-        yes ? write_skill(ctx, target, text) : skill_card(ctx, target, text)
+        [target, substitutions.reduce(File.read(source)) { |skill, (placeholder, value)| skill.gsub(placeholder, value) }]
+      end
+
+      # Whether the peer's installed skill isn't what install-skill would
+      # write (an older bundle's, or the user's edit): the status card says
+      # so. Not installed, or unreadable: no.
+      def skill_differs?(ctx)
+        target, text = skill_target_and_text(ctx)
+        text && File.file?(target) && File.read(target) != text
+      rescue SystemCallError
+        false
       end
 
       def skill_card(ctx, target, text)
@@ -351,7 +370,7 @@ module Samagotchi
       def follow_up(kind)
         case kind
         when "context" then "#{self.class::NAME} takes it in; it answers only if something in it is wrong."
-        else "#{self.class::NAME}'s answer comes as an update of the #{self.class::REVIEW} context; don't wait or poll."
+        else "#{self.class::NAME}'s answer comes as an update of the #{self.class::OUTBOX} context; don't wait or poll."
         end
       end
 

data/lib/samagotchi/sessions_command.rb

@@ -37,7 +37,8 @@ module Samagotchi
         archive ID...   # hide sessions (and their delegates) from every list and keep them for good; unarchive ID... brings them back
         delete [--force] ID...   # delete sessions for good (IDs or unique prefixes); --force stops a live worker first
         prune [--dry-run] [--days N] [--keep N] [--keep-status running,...] [--test-only]
-        clean [--dry-run] [--days N]   # test sessions (SAMAGOTCHI_ENV=test, CI) and leftover chi scratch ones: all of them, or those older than N days
+        clean [--dry-run] [--days N] [--all]   # test sessions (SAMAGOTCHI_ENV=test, CI) and leftover chi scratch ones: all of them, or those older than N days
+             --all: every session, not only test and scratch ones (by the age and count limits, as prune)
         stats ID [--format text|json]   # a session's cost, tokens and progress, without running a model turn:
              a live worker's GET stats, else the snapshot its saved analytics.json rebuilds (never starts a worker)
       Defaults: days=14 keep=500 keep_status=none (config: session.retention_days, session.max_count, session.keep_status)
@@ -107,6 +108,8 @@ module Samagotchi
       return parsed if parsed.is_a?(Integer)
 
       @opts = integers(parsed.options)
+      return usage_error(@opts) if @opts.is_a?(String)
+
       case @sub
       when "list" then list
       when "stop" then stop(parsed.args)
@@ -121,9 +124,15 @@ module Samagotchi
     def command_name = @sub && SUBCOMMANDS.include?(@sub) ? "chi sessions #{@sub}" : "chi sessions"
     def usage_text = { "stop" => STOP_USAGE, "restart" => RESTART_USAGE, "stats" => STATS_USAGE }.fetch(@sub, USAGE)
 
-    # quirk: a number that isn't one is 0 (--days=abc turns the age limit off)
+    # The options with --days, --keep and --limit as integers, or the usage
+    # error's message for one that isn't a whole number (--days=abc must not
+    # turn the age limit off).
+    # @return [Hash, String]
     def integers(options)
-      options.to_h { |key, value| [key, INTEGER_OPTIONS.include?(key) ? value.to_i : value] }
+      bad = options.find { |key, value| INTEGER_OPTIONS.include?(key) && !value.to_s.match?(/\A-?\d+\z/) }
+      return "--#{bad[0]} takes a whole number, got #{bad[1].to_s.inspect}" if bad
+
+      options.to_h { |key, value| [key, INTEGER_OPTIONS.include?(key) ? Integer(value, 10) : value] }
     end
 
     # The flags a list row carries: a chi scratch session, a test run, an

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -1328,7 +1328,12 @@ module Samagotchi
       def join_tool_line(part, duration_ms: nil)
         output = part[:output]
         command = part.dig(:view, :truncated) ? nil : part.dig(:view, :command)
-        status = output.nil? ? "no result" : ToolActivity.tool_activity_status(output, part[:tool], command: command)
+        status = if output.nil?
+                   "no result"
+                 else
+                   ToolActivity.tool_activity_status(ToolActivity.saved_result_text(output), part[:tool],
+                                                     command: command)
+                 end
         activity = { action: part[:label] || ToolActivity.tool_activity_action(part[:tool]), tool: part[:tool],
                      params: part[:params], status: status,
                      description: ToolView.description_title(part[:view] || {}) }

data/lib/samagotchi/tool_activity.rb

@@ -35,6 +35,14 @@ module Samagotchi
 
     module_function
 
+    # A saved tool output's leading "ran as: …" line (ToolRunner#changed_call_line) and "[tool]" lead (the
+    # shape of ToolResponse::LEAD), which the live status never sees: it reads the tool's own result.
+    SAVED_LEAD = /\A(?:ran as: [^\n]*\n)?\[[^\]\s]+\](?:\n| |\z)/
+
+    # A saved output (what the model got) as the tool's own text, for tool_activity_status.
+    # Without a "[tool]" lead (an older or hand-made output) it stays as it is.
+    def saved_result_text(output) = output.to_s.sub(SAVED_LEAD, "")
+
     # @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)
@@ -211,12 +219,16 @@ module Samagotchi
     # exited non-zero (its last "exit: N" line; no number: killed by a
     # signal), so the turn tally's "(N failed)" counts it; but not a grep
     # that found nothing (no_match?, given the +command+): that stays "ok".
+    # Also for a task_wait whose task failed (exited non-zero or without an
+    # exit code): its header's status, never a line of the log's tail.
     # "stopped" for a
     # task_wait the user's Stop ended (the task itself runs on), for one
     # whose task was stopped (the stop-task button, or the model's task_stop),
     # and for a command the user's Stop (or a signal to chi, a session stop)
     # killed or kept from starting: a cancel, not a failure (its text still
     # starts "Error:" for the model).
+    # A task_wait's own outcome is read from its header alone: the log's tail
+    # can print any line, "status: stopped" included.
     def tool_activity_status(result, tool_name = nil, command: nil)
       text = result.to_s
       return "stopped" if [Tools::Execute::NOT_RUN_ON_STOP, *Tools::Execute::NOT_RUN.values].include?(text)
@@ -230,7 +242,13 @@ module Samagotchi
       if tool_name == Tools::Execute::NAME && execute_failed?(text)
         return no_match?(text, command) ? "ok" : "error"
       end
-      return "stopped" if tool_name == Tools::TaskWait::NAME && text.match?(/^(wait_result: canceled|status: stopped)$/)
+
+      if tool_name == Tools::TaskWait::NAME
+        # The header: every line before the log's tail (output_tail:), which can print any line.
+        header = text.split(/^output_tail:$/, 2).first.to_s
+        return "stopped" if header.match?(/^(wait_result: canceled|status: stopped)$/)
+        return "error" if header[/^status: (\S+)$/, 1] == "failed"
+      end
 
       "ok"
     end

data/lib/samagotchi/tool_output_cut.rb

@@ -0,0 +1,321 @@
+# 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/
+
+    # What a web row keeps of a tool's output, on a reload
+    # (Web::MessageParts) and a mid-turn join (Bridge::TurnAccumulator): the
+    # row shows 300 chars and the rest on hover. A longer one keeps its head
+    # and tail (preview).
+    WEB_PREVIEW_CHARS = 2000
+
+    # 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. A command a signal
+    # ended (a segfault, an OOM kill) has an exit line with no number
+    # ("exit: "): it ended, so its output is all there is. The JS twin is
+    # turn_html.js's EXIT_LINE.
+    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