samagotchi 0.38.0 → 0.40.0

data/lib/samagotchi/llm_context_edit.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # One edit of what the model is sent (LLMContextView): a tool output,
+  # named by its id (ToolIds), sent as a stub instead of its text. Saved
+  # on the tool_response entry it changes, under +edits+ (plan D3), keyed
+  # by the id, as plain JSON: {"t42" => {"kind" => "stale", "note" => …,
+  # "by" => …, "staged_at" => …, "applied_at" => …}}, so it goes wherever
+  # the entry goes and a save and load keeps it as written.
+  #
+  # Copies of an entry share its edits Hash: a rollback checkpoint
+  # (Engine#clone_messages), the kernel's duplicate_conversation and a
+  # plugin's sessions.fork copy each entry's top level only. So the edits
+  # are replaced, never changed in place (.store), or an edit would reach
+  # a checkpoint it was rolled back from.
+  #
+  # kind: :stale (chi saw a later read or edit supersede it) or :forget
+  # (the model forgot it, its note keeping the finding); note: what the
+  # stub says; by: who made it ("chi", the model); staged_at/applied_at:
+  # ISO 8601 times, applied_at nil while it waits to reach the prompt;
+  # keep: the output's lines a forget keeps ([[first, last], …], as the
+  # model named them; saved only when there are some), sent under the
+  # stub; keep_offset: what those numbers are past the output's own lines
+  # (a ranged read's start_line - 1: a read's keep names file lines; saved
+  # only when not 0).
+  LLMContextEdit = Data.define(:id, :kind, :note, :by, :staged_at, :applied_at, :keep, :keep_offset) do
+    def initialize(keep: [], keep_offset: 0, **fields) = super
+
+    def applied? = !applied_at.nil?
+
+    def keep? = !keep.empty?
+
+    # What the model reads instead of the output, after the output's
+    # "[name]" lead.
+    def stub
+      kind == :forget ? "(forgotten) #{note}" : note.to_s
+    end
+
+    # The saved form, without the id (it is the key).
+    def to_h
+      saved = { "kind" => kind.to_s, "note" => note, "by" => by, "staged_at" => staged_at, "applied_at" => applied_at }
+      saved = saved.merge("keep" => keep) if keep?
+      keep_offset.zero? ? saved : saved.merge("keep_offset" => keep_offset)
+    end
+  end
+
+  class LLMContextEdit
+    KINDS = %i[stale forget].freeze
+
+    # +hash+ as saved (string or symbol keys), or nil for one of no known
+    # kind.
+    def self.from_h(id, hash)
+      return nil unless hash.is_a?(Hash)
+
+      field = ->(key) { hash.key?(key.to_s) ? hash[key.to_s] : hash[key] }
+      kind = field.call(:kind).to_s.to_sym
+      return nil unless KINDS.include?(kind)
+
+      new(id: id.to_s, kind: kind, note: field.call(:note).to_s, by: field.call(:by), staged_at: field.call(:staged_at),
+          applied_at: field.call(:applied_at), keep: ranges(field.call(:keep)),
+          keep_offset: field.call(:keep_offset).is_a?(Integer) ? [field.call(:keep_offset), 0].max : 0)
+    end
+
+    # Saved keep ranges as [[first, last], …]: pairs of positive Integers,
+    # first <= last; anything else is dropped.
+    def self.ranges(raw)
+      Array(raw).filter_map do |pair|
+        first, last = pair if pair.is_a?(Array) && pair.size == 2
+        [first, last] if first.is_a?(Integer) && last.is_a?(Integer) && first.positive? && first <= last
+      end
+    end
+
+    # +entry+ without the edit +id+ (a restore): a new edits Hash, as
+    # .store; no edits key when none is left.
+    def self.remove(entry, id)
+      return entry unless entry[:edits].is_a?(Hash) && entry[:edits].key?(id)
+
+      left = entry[:edits].except(id)
+      left.empty? ? entry.delete(:edits) : entry[:edits] = left
+      entry
+    end
+
+    # +entry+ with +edit+ saved on it: a new edits Hash, never the old one
+    # changed (copies of the entry share that one).
+    def self.store(entry, edit)
+      entry[:edits] = (entry[:edits].is_a?(Hash) ? entry[:edits] : {}).merge(edit.id => edit.to_h)
+      entry
+    end
+
+    # The edits saved on +entry+, by id.
+    # @return [Hash{String => LLMContextEdit}]
+    def self.on(entry)
+      saved = entry[:edits]
+      return {} unless saved.is_a?(Hash)
+
+      saved.each_with_object({}) do |(id, hash), edits|
+        edit = from_h(id, hash)
+        edits[edit.id] = edit if edit
+      end
+    end
+  end
+end

data/lib/samagotchi/llm_context_forget.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "tool_response"
+require_relative "tool_ids"
+require_relative "token_usage"
+require_relative "llm_context_edit"
+require_relative "llm_context_stale"
+require_relative "llm_context_apply"
+require_relative "llm_context_view"
+require_relative "tools/forget_outputs"
+
+module Samagotchi
+  # The forget layer (LLMContextStrategy :forget, experimental): the
+  # model's forget_outputs call on the running turn's conversation. A
+  # forget saves an LLMContextEdit of kind :forget on each output's entry
+  # (LLMContextEdit.store), staged (no applied_at); the apply rule
+  # (LLMContextApply, run at once by +apply+) then sends the batch at the
+  # next request or holds it for the turn's end, and the result says which.
+  # A restore takes a forget off (staged or applied); it goes out with the
+  # next request.
+  #
+  # Only the model's own tool outputs, named by their stored ids
+  # (ToolIds): never the system prompt, a user message, a steer or a
+  # context note (they have no id), never a legacy entry's derived id, and
+  # the call stays with its result (only the result's text is stubbed). Per
+  # id, refused with a reason:
+  # - an output from the last +protect_steps+ steps (the model may still
+  #   be working with it);
+  # - a read of a file an edit or write touched in those steps
+  #   (LLMContextStale.protected_ids), unless the forget keeps some of its
+  #   lines (keep): wiping what the model edits against makes it redo the
+  #   read (CLM's lesson);
+  # - a keep that holds all of the output, an output too small for a stub
+  #   to free anything (SMALL), an output already stubbed or forgotten, an
+  #   id nothing in context has.
+  # A read is never restored: reading the file again is its restore, and
+  # the file may have changed.
+  module LLMContextForget
+    BY = "model"
+    READ = "read"
+    # An output this short (its text after the lead, in chars) frees
+    # nothing as a stub ("(forgotten with t41: see its note) [restore: t42]").
+    SMALL = 80
+
+    # The turn a forget_outputs call runs in: its conversation (the
+    # entries the edits are saved on) and its ContextStatus (nil: none).
+    Turn = Data.define(:conversation, :context)
+
+    # One output a call may name: its entry, its ToolIds ref, its tool,
+    # its text (without the "[name]" lead) and its step; +offset+: what
+    # turns a line of its text into the line a keep names (a read's file
+    # lines: start_line - 1), +preview+: a read that came back as a big
+    # file's head/tail preview (no file lines to keep).
+    Output = Data.define(:index, :ref, :name, :body, :step, :offset, :preview) do
+      def read? = name == READ
+
+      # The lines a keep may name: [first, last].
+      def lines = [offset + 1, offset + body.lines.size]
+    end
+
+    module_function
+
+    # Runs a forget_outputs +call+ on +turn+, under the turn's
+    # +llm_context+ (LLMContextStrategy::Resolved: its layers and
+    # protect_steps). The conversation's last step is the one holding the
+    # call (both loops add the model's entry before its calls run).
+    # @param apply [#call] → LLMContextApply::Outcome: the apply rule at a
+    #   request, on the turn's conversation (KernelLoop#apply_llm_context!)
+    # @return [String] the tool result
+    def call(turn, call, llm_context:, apply:, root: Dir.pwd, now: Time.now.utc.iso8601(3))
+      request = Tools::ForgetOutputs.parse(call)
+      conversation = turn.conversation
+      return restore(turn, request.restore, llm_context) if request.restore? && request.ids.empty?
+      return "Error: forget_outputs needs ids to forget (or restore: ids to bring back)" if request.ids.empty?
+      if request.note.empty?
+        return "Error: forget_outputs needs a note: what you learned from these outputs (facts, file:line, " \
+               "what's ruled out, NEXT), since it is all that stays of them"
+      end
+
+      forgotten, refused = forget(conversation, request, llm_context.protect_steps, root, now)
+      lines = if forgotten.empty?
+                ["nothing forgotten"]
+              else
+                [applied_line(conversation, forgotten, apply.call, llm_context.active_layers)]
+              end
+      lines << restore(turn, request.restore, llm_context) if request.restore?
+      lines.concat(refused_lines(refused))
+      lines.join("\n")
+    end
+
+    # Saves a staged forget on each output +request+ names that may go.
+    # @return [Array(Array<String>, Hash{String => String})] the ids
+    #   forgotten, and the refused ones with why
+    def forget(conversation, request, protect_steps, root, now)
+      outputs = outputs(conversation)
+      last = LLMContextStale.step_count(conversation)
+      # The steps before the call's own: protected_ids counts that one too.
+      kept_reads = LLMContextStale.protected_ids(conversation, steps: protect_steps.positive? ? protect_steps + 1 : 0,
+                                                               root: root)
+      refused = {}
+      forgotten = request.ids.select do |id|
+        why = refusal(conversation, outputs[id], request.keep[id], last, protect_steps, kept_reads)
+        refused[id] = why if why
+        why.nil?
+      end
+      forgotten.each do |id|
+        output = outputs[id]
+        keep = request.keep.fetch(id, [])
+        edit = LLMContextEdit.new(id: id, kind: :forget, note: request.note, by: BY, staged_at: now, applied_at: nil,
+                                  keep: keep, keep_offset: keep.empty? ? 0 : output.offset)
+        LLMContextEdit.store(conversation[output.index], edit)
+      end
+      [forgotten, refused]
+    end
+
+    # Why +output+ can't go (a String for the result), nil when it can.
+    # +last+: the call's own step; the protect_steps steps before it are
+    # the model's latest outputs.
+    def refusal(conversation, output, keep, last, protect_steps, kept_reads)
+      return "no output with that id in context (ids look like t42)" unless output
+      return "already forgotten or stubbed" if LLMContextEdit.on(conversation[output.index]).key?(output.ref.id)
+      if protect_steps.positive? && output.step >= last - protect_steps
+        return "from your last #{protect_steps} step#{"s" unless protect_steps == 1}; you may still need it, forget it later"
+      end
+      return keep_refusal(output, keep) if keep
+
+      if kept_reads.include?(output.ref.id)
+        first, = output.lines
+        return "a read of a file you edited in your last #{protect_steps} steps; keep the lines you edit against " \
+               "(keep: [\"#{output.ref.id}:#{first}-#{first + 20}\"]) or forget it later"
+      end
+      return "too small: its stub would free nothing" if output.body.length <= SMALL
+
+      nil
+    end
+
+    # Why +keep+ can't be kept of +output+, nil when it can: a preview has
+    # no file lines, a range must fall in the output's lines, and some of
+    # it must go.
+    def keep_refusal(output, keep)
+      return "a preview of a big file: keep needs its lines; read a range of it instead" if output.preview
+
+      first, last = output.lines
+      outside = keep.reject { |from, to| from <= last && to >= first }
+      unless outside.empty?
+        shown = outside.map { |from, to| "#{from}-#{to}" }.join(", ")
+        return "keep #{shown} is outside its lines (#{first}-#{last}#{", the file's" if output.read?})"
+      end
+      kept = keep.flat_map { |from, to| ([from, first].max..[to, last].min).to_a }.uniq.size
+      return "keep holds all of it; nothing to forget" if kept >= last - first + 1
+
+      nil
+    end
+
+    # Takes the forgets of +ids+ off: any that hasn't reached the prompt
+    # yet, and one that has unless it is a read's (reading the file again
+    # is its restore). The next request sends them whole, whatever the
+    # apply rule (the model wants the text now), so the context estimate
+    # starts over (ContextStatus#edited!).
+    # @return [String] the result's line(s)
+    def restore(turn, ids, llm_context)
+      conversation = turn.conversation
+      outputs = outputs(conversation)
+      restored = []
+      refused = {}
+      sent = false
+      ids.each do |id|
+        output = outputs[id]
+        edit = output && LLMContextEdit.on(conversation[output.index])[id]
+        if edit.nil? || edit.kind != :forget
+          refused[id] = "not forgotten"
+        elsif output.read? && edit.applied?
+          refused[id] = "a read: read the file again instead (it may have changed)"
+        else
+          LLMContextEdit.remove(conversation[output.index], id)
+          restored << output
+          sent ||= edit.applied?
+        end
+      end
+      lines = restored.empty? ? [] : [restored_line(turn, restored, sent, llm_context)]
+      (lines + refused_lines(refused)).join("\n")
+    end
+
+    def restored_line(turn, restored, sent, llm_context)
+      ids = restored.map { |output| output.ref.id }.join(", ")
+      return "restored #{ids}: its stub was never sent" unless sent
+
+      turn.context&.edited!
+      view = LLMContextView.new(strategy: llm_context.active_layers)
+      tail = LLMContextView.chars(view.messages(turn.conversation)[restored.map(&:index).min..])
+      "restored #{ids}: the next request sends it whole again, now whatever llm_context.apply says (the server " \
+        "reads the #{k(tail)} from it on again)"
+    end
+
+    # Every output in +conversation+ a stored id names and that pairs with
+    # its call for sure (LLMContextStale.paired_runs), by id.
+    # @return [Hash{String => Output}]
+    def outputs(conversation)
+      LLMContextStale.paired_runs(conversation).each_with_object({}) do |run, found|
+        next if run.ref.derived?
+
+        name = run.call[:name].to_s
+        body = run.text.sub(ToolResponse::LEAD, "")
+        found[run.ref.id] = Output.new(index: run.index, ref: run.ref, name: name, body: body, step: run.step,
+                                       offset: name == READ ? read_offset(run.call) : 0,
+                                       preview: name == READ && LLMContextStale.partial?(body))
+      end
+    end
+
+    # A read's first line, less one (start_line; 1 without one).
+    def read_offset(call)
+      first = Integer(call[:start_line].to_s.strip, 10)
+      first.positive? ? first - 1 : 0
+    rescue ArgumentError, TypeError
+      0
+    end
+
+    # What the apply rule did with the batch the forgotten ids are in.
+    def applied_line(conversation, forgotten, outcome, layers)
+      ids = forgotten.join(", ")
+      applied = outcome.applied.map(&:id)
+      if forgotten.all? { |id| applied.include?(id) }
+        return "forgot #{ids}: applied, the next request sends the stubs (#{frees(outcome.freed_chars)}; the " \
+               "server reads the #{k(outcome.tail_chars)} after them again)"
+      end
+
+      freed, = LLMContextApply.weigh(conversation, layers: layers, edits: staged(conversation))
+      "forgot #{ids}: staged until the turn ends (the staged stubs: #{frees(freed)} then)"
+    end
+
+    # The edits saved unapplied, as [entry index, edit] pairs.
+    def staged(conversation)
+      conversation.each_with_index.flat_map do |entry, index|
+        next [] unless entry[:role].to_s == "tool_response"
+
+        LLMContextEdit.on(entry).values.reject(&:applied?).map { |edit| [index, edit] }
+      end
+    end
+
+    def refused_lines(refused)
+      return [] if refused.empty?
+
+      ["not done:"] + refused.map { |id, why| "- #{id}: #{why}" }
+    end
+
+    def frees(chars) = chars.positive? ? "frees #{k(chars)}" : "frees nothing, the stubs are as long"
+
+    # "12.4k tokens", chars/4.
+    def k(chars)
+      tokens = (chars / TokenUsage::CHARS_PER_TOKEN).ceil
+      tokens >= 1000 ? format("%.1fk tokens", tokens / 1000.0) : "#{tokens} tokens"
+    end
+
+    private_class_method :forget, :refusal, :keep_refusal, :restored_line, :read_offset, :applied_line, :staged,
+                         :refused_lines, :frees, :k
+  end
+end

data/lib/samagotchi/llm_context_stale.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "tool_response"
+require_relative "tool_ids"
+require_relative "llm_context_edit"
+require_relative "model_profile"
+require_relative "tool_call_parser"
+require_relative "tools/builtin_calls"
+require_relative "tools/tool_path"
+
+module Samagotchi
+  # The stale layer (LLMContextStrategy :stale): a file read that a later
+  # read superseded is sent as a stub, "[read] lib/x.rb lines 1-200:
+  # superseded by a later read". Deterministic: no model call, no note of
+  # the model's. Superseded means a later read of the same file covering
+  # the read's lines, or (#found's +changes+) a successful edit or write of
+  # the file: "superseded by a later edit". A run that failed (its output
+  # an "Error") or holds only part of what it asked for supersedes nothing.
+  # Edit-driven stubs are opt-in (llm_context.stale_edits); when one may be
+  # sent is LLMContextApply's rule (the user, 2026-10-07: never mid-edit),
+  # and no read of a file the last steps edited is stubbed
+  # (#protected_ids). Shell reads (cat, sed -n) don't count.
+  #
+  # Nothing per run says what a built-in call read, so the calls are worked
+  # out from the model entries, in both formats: a chat entry's tool_calls,
+  # paired with each result by tool_call_id; a native entry's call markup
+  # (Qwen's <tool_call>, Gemma's <|tool_call>, whichever the entry holds: a
+  # session may have switched models), paired in order with the runs of the
+  # joined result after it. A result whose runs don't open with their calls'
+  # "[name]" leads (ToolResponse.runs_named; a corrected call's "ran as:"
+  # line) is left alone.
+  #
+  # A stub names its run by its ToolIds id (ToolIds.refs_at: stored, or
+  # derived for a legacy entry); LLMContextApply saves it on the entry
+  # (LLMContextEdit.store) when its rule lets it through. A run with any
+  # edit already keeps it.
+  module LLMContextStale
+    BY = "chi"
+    READ = "read"
+    CHANGES = %w[edit write].freeze
+    WHOLE = (1..Float::INFINITY)
+
+    # A file call's run: the entry it sits in (+index+) and its ToolIds
+    # ref, the call's tool, the path as the model wrote it (+shown+) and
+    # expanded, the lines a read asked for (WHOLE for all), whether its
+    # output is an error, whether it holds only part of what was asked
+    # (#partial?), the output's length, and its step (1 for the
+    # conversation's first model entry with calls, one more per such
+    # entry).
+    FileRun = Data.define(:index, :ref, :name, :shown, :path, :lines, :failed, :partial, :size, :step) do
+      def read? = name == READ
+
+      # +other+, an earlier read of the same file, is stale after this
+      # run: a read covering its lines, or (+changes+) an edit or write.
+      def supersedes?(other, changes: false)
+        return false if failed || partial || path != other.path
+        return changes unless read?
+
+        lines.begin <= other.lines.begin && lines.end >= other.lines.end
+      end
+    end
+
+    # A read to stub (#found). #change? when only an edit or write
+    # superseded it (+changes+), no later read.
+    Found = Data.define(:run, :by, :note) do
+      def change? = !by.read?
+    end
+
+    module_function
+
+    # The reads to stub that have no edit yet: each read, the first later
+    # run that superseded it (+by+; the replay benchmark applies the edit
+    # at the request after it, as chi does) and the stub's note. A stub
+    # that wouldn't be shorter than the output is left out. +changes+: a
+    # successful edit or write of the file supersedes a read too, when no
+    # later read does (a later read is +by+ whenever there is one, so
+    # Found#change? holds only for a read nothing but a change superseded).
+    # Whether such a stub may be sent yet is LLMContextApply's call (the
+    # user, 2026-10-07: right after an edit the model is usually still
+    # editing against the read): at turn end, or when it pays off, and
+    # never the read #protected_ids names.
+    # @return [Array<Found>]
+    def found(conversation, root: Dir.pwd, changes: false)
+      runs = file_runs(conversation, root)
+      runs.each_with_index.filter_map do |run, at|
+        next unless run.read?
+        next if LLMContextEdit.on(conversation[run.index]).key?(run.ref.id)
+
+        later = runs[(at + 1)..]
+        by = later.find { |other| other.read? && other.supersedes?(run) } ||
+             (changes && later.find { |other| other.supersedes?(run, changes: true) })
+        next unless by
+
+        note = note(run, by)
+        Found.new(run: run, by: by, note: note) if run.size > "[#{run.name}] #{note}".length
+      end
+    end
+
+    # The ids of the reads stale never stubs: every read of each file an
+    # edit or write (successful or not: a failed one is retried) touched in
+    # the conversation's last +steps+ steps (protect_steps; 0: none). The
+    # model is likely still editing against them, and any of them may hold
+    # the lines it edits (an earlier range, or the only whole copy when a
+    # later read came back cut). Steps count across the conversation.
+    # @return [Set<String>]
+    def protected_ids(conversation, steps:, root: Dir.pwd)
+      return Set.new unless steps.positive?
+
+      runs = file_runs(conversation, root)
+      last = step_count(conversation)
+      edited = runs.select { |run| !run.read? && run.step > last - steps }.to_set(&:path)
+      runs.select { |run| run.read? && edited.include?(run.path) }.to_set { |run| run.ref.id }
+    end
+
+    # The conversation's steps: its model entries with calls.
+    def step_count(conversation)
+      conversation.count { |entry| entry[:role].to_s == "model" && !calls(entry).empty? }
+    end
+
+    # What the stub says after the "[read]" lead.
+    def note(run, by)
+      lines = if run.lines == WHOLE
+                ""
+              else
+                " lines #{run.lines.begin}-#{run.lines.end.infinite? ? "end" : run.lines.end}"
+              end
+      "#{run.shown}#{lines}: superseded by a later #{by.name}"
+    end
+
+    # One run of a tool_response entry paired with its call for sure
+    # (#results: by tool_call_id, or the batch's "[name]" leads in order):
+    # the entry's index, its ToolIds ref, the call, its text and its step.
+    PairedRun = Data.define(:index, :ref, :call, :text, :step)
+
+    # Every run of +conversation+ that pairs with its call, in order. A
+    # result whose runs don't open with their calls' leads (a "ran as:"
+    # line, an output holding the SEPARATOR and a lead) has none: what
+    # names a run (forget_outputs, the view's ids) leaves it alone.
+    # @return [Array<PairedRun>]
+    def paired_runs(conversation)
+      batch = []
+      step = 0
+      conversation.each_with_index.with_object([]) do |(entry, index), runs|
+        case entry[:role].to_s
+        when "model"
+          batch = calls(entry)
+          step += 1 unless batch.empty?
+        when "tool_response"
+          results(conversation, index, batch).each do |ref, call, text|
+            runs << PairedRun.new(index: index, ref: ref, call: call, text: text, step: step)
+          end
+        end
+      end
+    end
+
+    # The read, edit and write runs of +conversation+, in order.
+    # @return [Array<FileRun>]
+    def file_runs(conversation, root)
+      paired_runs(conversation).filter_map do |run|
+        file_run(run.index, run.ref, run.call, run.text, root, run.step)
+      end
+    end
+
+    # A model entry's calls, each [tool_call_id (nil for a native one), the
+    # call as dispatched (Tools::BuiltinCalls.build)].
+    def calls(entry)
+      if entry[:tool_calls].is_a?(Array) && !entry[:tool_calls].empty?
+        return entry[:tool_calls].map do |call|
+          [field(call, :id), Tools::BuiltinCalls.build(field(call, :name).to_s, arguments(field(call, :arguments)))]
+        end
+      end
+
+      content = entry[:content].to_s
+      parser = native_parser(content)
+      return [] unless parser
+
+      parser.read(parser.strip_thought(content)).map do |call|
+        [nil, Tools::BuiltinCalls.build(call[:name], call[:args], raw: call[:raw])]
+      end
+    end
+
+    # A tool_response entry's runs, each [its ref, its call, its text]; none
+    # when they can't be paired for sure.
+    def results(conversation, index, batch)
+      entry = conversation[index]
+      refs = ToolIds.refs_at(conversation, index)
+      if entry[:tool_call_id]
+        # Paired by an id its batch holds once: a provider may send an
+        # empty or repeated id, and a wrong pairing names the wrong file.
+        id = entry[:tool_call_id].to_s
+        matches = id.empty? ? [] : batch.select { |call_id, _| call_id.to_s == id }
+        call = matches.one? ? matches.first.last : nil
+        texts = call && refs.size == 1 ? ToolResponse.runs_named(entry[:content], [call[:name]]) : nil
+        return texts ? [[refs.first, call, texts.first.text]] : []
+      end
+
+      calls = batch.map(&:last)
+      texts = ToolResponse.runs_named(entry[:content], calls.map { |call| call[:name] })
+      return [] unless texts && texts.size == refs.size
+
+      refs.zip(calls, texts.map(&:text))
+    end
+
+    def file_run(index, ref, call, text, root, step)
+      name = call[:name].to_s
+      return nil unless name == READ || CHANGES.include?(name)
+
+      shown = (name == READ ? call[:content] : call[:path]).to_s.strip
+      return nil if shown.empty?
+
+      body = text.sub(ToolResponse::LEAD, "")
+      FileRun.new(index: index, ref: ref, name: name, shown: shown,
+                  path: File.expand_path(Tools::ToolPath.normalize(shown), root),
+                  lines: name == READ ? lines(call) : WHOLE, failed: body.lstrip.start_with?("Error"),
+                  partial: partial?(body), size: text.length, step: step)
+    end
+
+    # The read tool's head/tail preview of a big file (Tools::Read) or an
+    # output ToolRunner cut at max_tool_output_chars: it doesn't hold all
+    # the lines asked for, so it supersedes nothing.
+    PREVIEW = "[TRUNCATED_PREVIEW_HEAD]"
+    CUT = /\[cut: \d+ of \d+ chars; read it in parts\]\z/
+
+    def partial?(body)
+      body.start_with?("truncated=true") || body.include?(PREVIEW) || body.match?(CUT)
+    end
+
+    # The lines a read asked for: from start_line (1) to end_line (the end).
+    def lines(call)
+      first = line(call[:start_line]) || 1
+      last = line(call[:end_line]) || Float::INFINITY
+      first..last
+    end
+
+    def line(value)
+      number = value.is_a?(Integer) ? value : Integer(value.to_s.strip, 10)
+      number.positive? ? number : nil
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def field(hash, key)
+      return nil unless hash.is_a?(Hash)
+
+      hash.key?(key) ? hash[key] : hash[key.to_s]
+    end
+
+    def arguments(value)
+      return value if value.is_a?(Hash)
+
+      parsed = JSON.parse(value.to_s)
+      parsed.is_a?(Hash) ? parsed : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    QWEN_CALL = "<tool_call>"
+    GEMMA_CALL = "<|tool_call>"
+
+    def native_parser(content)
+      if content.include?(GEMMA_CALL)
+        @gemma ||= ToolCallParser::Gemma.new(ModelProfile.gemma4)
+      elsif content.include?(QWEN_CALL)
+        @qwen ||= ToolCallParser::Qwen.new(ModelProfile.qwen36)
+      end
+    end
+
+    private_class_method :file_runs, :results, :file_run, :lines, :line, :field, :arguments, :native_parser
+  end
+end