samagotchi 0.60.0 → 0.62.0

data/lib/samagotchi/bundles/github-pr/plugin.rb

@@ -20,8 +20,10 @@ require "tmpdir"
 # hunk, else the file at the PR's head. The PRs are the session's attached
 # github-pr sources and the PR URLs in the user's messages (a delegate
 # child's task is its first one). Display only (event[:present]): the
-# model's text stays as it was. The after_turn hook links from a per-PR
-# cache and never runs gh (the web holds the answer until the hooks are
+# model's text stays as it was. Each linked ref is also a file ref on the
+# answer (event[:refs], chi 0.61.0): the file in this checkout, with a "PR
+# diff" (or "File at head") action the web's ref menu offers. The
+# after_turn hook links from a per-PR cache and never runs gh (the web holds the answer until the hooks are
 # done); before_turn, before_generation and the init task fill the cache
 # off the turn's thread (`gh api`), in a session worker only: the REPL and
 # -p --non-interactive show no web page while they run (ctx.frontend; a chi
@@ -50,12 +52,17 @@ class Plugin
   OFFER_LINE = "Not attached: the agent gets nothing until you attach it."
   # first_prompt keeps this much of the prompt.
   FIRST_PROMPT_CHARS = 160
+  # A git remote URL's GitHub owner and repo (https, ssh or scp-like).
+  REMOTE_REPO = %r{github\.com[:/]([^/\s]+)/([^/\s]+?)(?:\.git)?/?\z}i
 
   def initialize
     @cache = PrCache.new
     @generation_checked_at = nil
     @warned_mode = false
     @warned_line_links = false
+    # cwd => the "owner/repo"s (downcased) its git remotes name on
+    # github.com, for the worker's life.
+    @checkout_repos = {}
   end
 
   def register(chi)
@@ -138,7 +145,39 @@ class Plugin
     cached = prs.filter_map { |pr| (data = @cache[pr]) && [pr, data] }
     return if cached.empty?
 
-    event[:present].call { |display| LineLinker.new(cached).link(display) }
+    linker = LineLinker.new(cached)
+    event[:present].call { |display| linker.link(display) }
+    add_refs(event[:refs], linker.found, ctx) unless linker.found.empty?
+  end
+
+  # Each linked `path:line` as a file ref on the answer (event[:refs]): its
+  # target the file in this checkout (its root + the PR path), its action
+  # the link's URL, named by what it opens. Only for a PR of this
+  # checkout's repo (one of its git remotes names it): another project's PR
+  # has its files elsewhere, so its links stay links.
+  def add_refs(refs, found, ctx)
+    return unless refs
+
+    root = project_root(ctx)
+    return unless root
+
+    repos = checkout_repos(ctx)
+    found.each do |hit|
+      next unless repos.include?(hit[:repo].downcase)
+
+      action = hit[:diff] ? { id: "pr_diff", label: "PR diff", url: hit[:url] } : { id: "blob", label: "File at #{hit[:at]}", url: hit[:url] }
+      refs.call(match: hit[:match], kind: "file", label: nil, actions: [action],
+                target: { path: File.join(root, hit[:path]), line: hit[:line], end_line: hit[:end_line] })
+    end
+  end
+
+  # The GitHub "owner/repo"s (downcased) the checkout's git remotes name
+  # (`git remote -v`: a fork's upstream too), asked once per cwd.
+  def checkout_repos(ctx)
+    @checkout_repos[ctx.cwd] ||= run(ctx, "git", "remote", "-v").to_s.each_line.filter_map do |line|
+      match = line.split(/\s+/)[1].to_s.match(REMOTE_REPO)
+      "#{match[1]}/#{match[2]}".downcase if match
+    end.uniq
   end
 
   # Fetches the PRs in +prs+ whose cache entry is missing or old, on this
@@ -580,9 +619,17 @@ class LineLinker
     nil
   end
 
+  # The refs the last #link linked, in order: {match:, url:, diff:, at:,
+  # repo:, path:, line:, end_line:} (+match+ the ref's text, inline code's
+  # without its backticks; +diff+ true for a PR diff URL, else +at+ "head"
+  # or "base", the sha of the file's URL; +repo+ the PR's "owner/repo";
+  # +path+ the PR's path of the file).
+  attr_reader :found
+
   # @param prs [Array<Array(PrRef, PrData)>]
   def initialize(prs)
     @prs = prs
+    @found = []
   end
 
   # +text+ with each ref that names exactly one PR's file as a markdown
@@ -591,8 +638,10 @@ class LineLinker
     head = text[0, MAX_SCAN]
     out = +""
     pos = 0
-    hits(head).each do |start, finish, url|
-      out << head[pos...start] << "[#{head[start...finish]}](#{url})"
+    @found = []
+    hits(head).each do |start, finish, hit|
+      out << head[pos...start] << "[#{head[start...finish]}](#{hit[:url]})"
+      @found << hit
       pos = finish
     end
     return text if pos.zero?
@@ -602,7 +651,11 @@ class LineLinker
 
   # The URL for +path+'s lines +from+..+to+ (+to+ nil: one line), or nil:
   # no PR has the file, or more than one does.
-  def url_for(path, from, to = nil)
+  def url_for(path, from, to = nil) = line_for(path, from, to)&.fetch(:url)
+
+  # {url:, diff:, path:, line:, end_line:} for +path+'s lines (see #url_for),
+  # or nil.
+  def line_for(path, from, to = nil)
     found = @prs.filter_map do |pr, data|
       file = resolve(data.files, path)
       [pr, data, file] if file
@@ -614,7 +667,7 @@ class LineLinker
 
   private
 
-  # [start, finish, url] for each ref to link, by offset.
+  # [start, finish, hit] for each ref to link, by offset (+hit+ as #found's).
   def hits(text)
     fences = fenced_blocks(text)
     skipped = fences + spans(text, URL_SPAN) + spans(text, MARKDOWN_LINK)
@@ -624,7 +677,7 @@ class LineLinker
       next if inside_any?(skipped, start, finish)
 
       match = inner.strip.match(REF_ALONE) or next
-      url = ref_url(match) and found << [start, finish, url]
+      hit = ref_line(match) and found << [start, finish, hit.merge(match: match[0])]
     end
     text.scan(REF) do
       match = Regexp.last_match
@@ -632,20 +685,20 @@ class LineLinker
       finish = match.end(0)
       next if inside_any?(skipped, start, finish) || inside_any?(code, start, finish)
 
-      url = ref_url(match) and found << [start, finish, url]
+      hit = ref_line(match) and found << [start, finish, hit.merge(match: match[0])]
     end
     found.sort_by(&:first)
   end
 
   # A path has a `/` or an extension (`10:30` is a time, `host:8080` a port).
-  def ref_url(match)
+  def ref_line(match)
     path = match[:path]
     return nil unless path.include?("/") || path.match?(/\.[A-Za-z0-9]+\z/)
 
     from = match[:from].to_i
     to = match[:to]&.to_i
     to = nil if to && to <= from
-    from.zero? ? nil : url_for(path, from, to)
+    from.zero? ? nil : line_for(path, from, to)
   end
 
   # The PR file +path+ names: the path (or a rename's old one) exactly,
@@ -687,18 +740,21 @@ class LineLinker
 
   # The PR's Files changed anchor when the lines are inside one hunk (the
   # new side; a removed file's old side), else the file at the PR's head
-  # (a removed one: at its base), which has every line.
+  # (a removed one: at its base), which has every line. As #line_for's
+  # hash.
   def line_url(pr, data, file, from, to)
     last = to || from
+    lines = { path: file.path, line: from, end_line: to, repo: "#{pr.owner}/#{pr.repo}" }
     hunks, side = file.removed? ? [file.old_hunks, "L"] : [file.new_hunks, "R"]
     if hunks.any? { |hunk| hunk.cover?(from) && hunk.cover?(last) }
       anchor = "#{side}#{from}#{"-#{side}#{to}" if to}"
-      return "#{pr.url}/files#diff-#{Digest::SHA256.hexdigest(file.path)}#{anchor}"
+      return { url: "#{pr.url}/files#diff-#{Digest::SHA256.hexdigest(file.path)}#{anchor}", diff: true, at: nil, **lines }
     end
 
     sha = file.removed? ? data.base_sha : data.head_sha
     path = file.path.split("/").map { |segment| segment.gsub(/[^\w.~-]/) { |c| c.bytes.map { |b| format("%%%02X", b) }.join } }
-    "https://github.com/#{pr.owner}/#{pr.repo}/blob/#{sha}/#{path.join("/")}#L#{from}#{"-L#{to}" if to}"
+    { url: "https://github.com/#{pr.owner}/#{pr.repo}/blob/#{sha}/#{path.join("/")}#L#{from}#{"-L#{to}" if to}", diff: false,
+      at: file.removed? ? "base" : "head", **lines }
   end
 
   # [start, finish, inner] for each inline code span outside +fences+: a

data/lib/samagotchi/bundles/slow-commands/manifest.yml

@@ -1,12 +1,12 @@
 ---
 name: slow-commands
-version: 0.2.0
+version: 0.2.1
 scope: system
 description: "Remembers commands that ran past the execute limit in a project; the next identical execute is denied once a turn with advice to run it with task_create and task_wait; /slow-commands lists and forgets them"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:bf2cfccbcadedcd85ea0b53f2d263c8729e14ed8cf310bca4a56affe50181292
+  sha256: sha256:cc8b9829ae77565d8d47969377e91124cf4c785164e417d3d323daeec1295269
 # Execute::HANDED_OVER, read when the plugin loads (0.59.0); after_tool_call's
 # call:, elapsed_ms: and result: (0.57.0)
 requires_chi: ">= 0.59.0"

data/lib/samagotchi/bundles/slow-commands/plugin.rb

@@ -75,7 +75,11 @@ class Plugin
   TIMED_OUT = /\A#{Regexp.escape(Samagotchi::Tools::Execute::TIMEOUT_PREFIX)} (\d+)s/
   # Still running at the limit, handed over as a task (chi >= 0.59.0).
   HANDED_OVER = /\A#{Regexp.escape(Samagotchi::Tools::Execute::HANDED_OVER)} (\d+)s limit/
-  STOPPED = [Samagotchi::Tools::Execute::STOPPED_BY_USER, Samagotchi::Tools::Execute::NOT_RUN_ON_STOP].freeze
+  # A stopped command's first words: the user's Stop, or a signal to chi
+  # (chi >= 0.62.0; an older chi has no such text).
+  STOPPED = %i[STOPPED_BY_USER NOT_RUN_ON_STOP STOPPED_BY_SIGNAL NOT_RUN_ON_SIGNAL].filter_map do |name|
+    Samagotchi::Tools::Execute.const_get(name) if Samagotchi::Tools::Execute.const_defined?(name)
+  end.freeze
   LEX = Samagotchi::Guardrails::ShellLex
   SHORT_CHARS = 60
   WAIT_DEFAULT = 600

data/lib/samagotchi/bundles/source-links/hooks/source_links.rb

@@ -2,6 +2,7 @@
 
 # Loaded through module_eval: it requires what it uses.
 require "open3"
+require "samagotchi/ref"
 
 # An after_turn hook that links the source refs the model's answer
 # mentions — a JIRA ticket, a GitHub issue, an internal wiki page. In the
@@ -27,6 +28,8 @@ require "open3"
 #           pattern: '\bGH-(\d+)\b'   # full form: a regex
 #           url: 'https://github.com/org/repo/issues/{match}'
 #           case_insensitive: false   # optional, default false
+#           kind: issue               # optional: the refs' kind (below),
+#                                     # default issue
 #         - name: Issues              # `#12` → this project's repo,
 #                                     # `owner/repo#12` → that repo
 #           pattern: '(?<![\w/&])(?:(?<repo>[A-Za-z0-9][\w-]*/[\w.-]*\w))?#(?<num>\d+)\b'
@@ -49,6 +52,12 @@ require "open3"
 # placeholder that can't be filled is not linked; a `{word}` that is none
 # of these stays text (warned at load).
 #
+# Each linked ref is also a ref on the answer (event[:refs], chi 0.61.0):
+# its source's `kind:` (a short lowercase word, default "issue"; not
+# "file"), target {id: the ref's text}, label "<name> <ref>", and one
+# action, "Open in <name>", the ref's URL. A URL that isn't http(s) stays a
+# markdown link only. The web's ref menu shows the action.
+#
 # The note is not stored in the conversation: it is an event, replayed by a
 # UI with the session's cards (a reload keeps it, after the worker stopped
 # too: cards.json). The links are stored as the answer's display. A ref in
@@ -75,6 +84,8 @@ class SourceLinks
   # Placeholders every pattern has: {match} (group 1, else the whole ref),
   # and {repo}/{host} (a named group, else the project's git remote).
   BUILTIN_PLACEHOLDERS = %w[match repo host].freeze
+  # A source's refs' kind, unless its `kind:` says another.
+  DEFAULT_KIND = "issue"
   # `git remote get-url` output: a URL with a scheme, `[user[:pw]@]host[:port]/path`.
   REMOTE_URL = %r{\A(?:https?|ssh|git)://(?:[^/]*@)?(\[[^\]]*\]|[^/:@]+)(?::[^/]*)?(/.*)?\z}i
   # scp-like `[user@]host:path`: a colon before any slash; a leading `/` or
@@ -117,6 +128,7 @@ class SourceLinks
 
     hits = occurrences(text[0, MAX_SCAN])
     linked = present_links(event[:present], text, hits)
+    add_refs(event[:refs], hits)
     return unless @note
 
     found = collect(hits)
@@ -144,6 +156,33 @@ class SourceLinks
     ours.nil? || shown != ours ? nil : linked
   end
 
+  # Each ref the answer links (#link's rule: not in code, the first source
+  # on a ref) as a ref on the answer, once per text and URL. Independent of
+  # the display (chi pairs it with the shown link by its URL). A URL that
+  # isn't http(s) can't be an action: that ref is left out.
+  def add_refs(refs, hits)
+    return unless refs
+
+    seen = {}
+    pos = 0
+    hits.each do |hit|
+      next if hit[:quiet] || hit[:start] < pos
+
+      pos = hit[:finish]
+      key = [hit[:ref], hit[:url]]
+      next if seen.key?(key) || !Samagotchi::RefAction.http_url?(hit[:url])
+
+      seen[key] = true
+      refs.call(match: hit[:ref], kind: hit[:kind], target: { id: hit[:ref] },
+                label: fit("#{hit[:name]} #{hit[:ref]}", Samagotchi::Ref::MAX_LABEL),
+                actions: [{ id: "open", label: fit("Open in #{hit[:name]}", Samagotchi::RefAction::MAX_LABEL), url: hit[:url] }])
+    end
+  end
+
+  # +text+ cut to +max+ characters with a "…", so a long source name can't
+  # get its refs refused.
+  def fit(text, max) = text.length > max ? "#{text[0, max - 1]}…" : text
+
   # The content of the last `role: "model"` message, or nil. Handles both
   # string- and symbol-keyed messages. A turn that ended without a visible
   # answer stores a `kind: turn_note` system message instead, so the role
@@ -188,7 +227,8 @@ class SourceLinks
           next if url.nil?
 
           quiet = inside_any?(code, start, finish) || inside_any?(labels, start, finish)
-          hits << { start: start, finish: finish, name: source[:name], ref: match[0], url: url, quiet: quiet }
+          hits << { start: start, finish: finish, name: source[:name], kind: source[:kind], ref: match[0], url: url,
+                    quiet: quiet }
         end
       rescue Regexp::TimeoutError
         Samagotchi::Log.warn(:hooks, "source_links_timeout",
@@ -407,7 +447,7 @@ class SourceLinks
       name = prefix if name.empty?
       regex = Regexp.new("\\b#{Regexp.escape(prefix)}-(\\d+)\\b", flags, timeout: REGEX_TIMEOUT)
       base = entry["base_url"].to_s
-      { name: name, regex: regex, url: ->(ref, _match) { "#{base}#{ref}" } }
+      { name: name, kind: ref_kind(name, entry["kind"]), regex: regex, url: ->(ref, _match) { "#{base}#{ref}" } }
     elsif !pattern.empty?
       name = "source" if name.empty?
       regex = Regexp.new(pattern, flags, timeout: REGEX_TIMEOUT)
@@ -416,7 +456,7 @@ class SourceLinks
       remote = entry["remote"].to_s.strip
       remote = "origin" if remote.empty?
       hosts = Array(entry["remote_host"]).map { |host| host.to_s.strip.downcase }.reject(&:empty?)
-      source = { name: name, remote: remote, remote_hosts: hosts }
+      source = { name: name, kind: ref_kind(name, entry["kind"]), remote: remote, remote_hosts: hosts }
       source.merge(regex: regex, url: ->(ref, match) { render_url(template, known, match, ref, source) })
     else
       warn_invalid("a source needs a prefix: or a pattern:")
@@ -427,6 +467,21 @@ class SourceLinks
     nil
   end
 
+  # A source's `kind:` for its refs: a short lowercase word other than
+  # "file" (a file ref needs a path), else DEFAULT_KIND, with a warning
+  # when one was given.
+  def ref_kind(name, raw)
+    return DEFAULT_KIND if raw.nil? || raw.to_s.strip.empty?
+
+    kind = raw.to_s.strip
+    return kind if Samagotchi::Ref::KIND.match?(kind) && kind != Samagotchi::Ref::FILE
+
+    Samagotchi::Log.warn(:hooks, "source_links_invalid_kind",
+                         echo: "[samagotchi:hooks] source-links: #{name}: kind #{kind.inspect} is not a short " \
+                               "lowercase word (nor file); using #{DEFAULT_KIND}")
+    DEFAULT_KIND
+  end
+
   # The placeholders of +template+ this pattern can fill: {match}, {repo},
   # {host}, its named groups and {1}…{N} for its N groups. Any other
   # `{word}` stays as text, with one warning here, at compile time.

data/lib/samagotchi/bundles/source-links/manifest.yml

@@ -1,15 +1,15 @@
 ---
 name: source-links
-version: 0.4.0
+version: 0.5.0
 scope: system
 description: Links source refs (JIRA tickets, GitHub issues, …) in the model's answer — inline links in the web, and a one-line note after the turn (note false turns it off); sources are configured patterns
 trust_level: reviewed
-requires_chi: ">= 0.35.0"
+requires_chi: ">= 0.61.0"
 files:
-  source_links.md: sha256:1670a3051b67610f41a680fc8e61bc1c99657a87f0f32121d040e05512896748
+  source_links.md: sha256:ace01a0f7c308a0ae54ece714c31c0e6d7a49c372d98111030e6d268320bed3a
 hooks:
   source_links.rb:
-    sha256: sha256:8ce4d11659f4bc151167f99e47299c0f6ef246797c9167c609c1699e3edea2e5
+    sha256: sha256:8d84c68be88972737905925bc9fc4bd941007fb945e8104e9f6b3d61a1186b89
     event: after_turn
     on_error: log
     priority: 90

data/lib/samagotchi/bundles/source-links/source_links.md

@@ -2,4 +2,4 @@
 
 The `source-links` bundle's `after_turn` hook links the source refs (a JIRA ticket, a GitHub issue, …) in your answers. In the web, each ref in the answer becomes a link; that is how the answer is **shown**, not what you wrote: your own message keeps the plain ref. A `sources: NAME ref → url, …` line right after an answer is the same hook's note (the terminals only see this line). The web leaves it out when markdown is on and the answer links every ref it names; otherwise every UI shows it. The line is **not part of the conversation**: it is an event, so it is not in the session file and you cannot refer back to it. A UI replays it with the session's cards (a page reload keeps it, after the worker stopped too).
 
-The refs come from the `bundles: source-links:` section of config.yml: each source is a `prefix:` + `base_url:` pair (simple) or a `pattern:` regex + `url:` template (full form), plus an optional `max:` for refs per line and `note: false` to drop the line (the web links stay). A `url:` template can take the project's own repo from its git remote, so a bare `#12` links to this project's issue and `owner/repo#12` to that repo's. With no sources configured the hook does nothing. A ref already inside a URL is not linked again, and a ref in code or in a markdown link is not linked in the answer.
+The refs come from the `bundles: source-links:` section of config.yml: each source is a `prefix:` + `base_url:` pair (simple) or a `pattern:` regex + `url:` template (full form), plus an optional `kind:` per source (what the web's ref menu calls its refs, default `issue`), an optional `max:` for refs per line and `note: false` to drop the line (the web links stay). A `url:` template can take the project's own repo from its git remote, so a bare `#12` links to this project's issue and `owner/repo#12` to that repo's. With no sources configured the hook does nothing. A ref already inside a URL is not linked again, and a ref in code or in a markdown link is not linked in the answer.

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.60.0
+version: 0.62.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/engine.rb

@@ -64,6 +64,7 @@ require_relative "sampling_settings"
 require_relative "thinking"
 require_relative "reasoning_history"
 require_relative "answer_display"
+require_relative "answer_refs"
 require_relative "edit_preview"
 require_relative "question_desk"
 require_relative "child_reports"
@@ -287,6 +288,9 @@ module Samagotchi
       self.guardrail_state_dir = Session.default_state_dir
       # list_sessions and send_note speak for whichever session runs now.
       @kernel.peers = PeerView.new(self)
+      # A plugin tool's row refs resolve against the session's folder, as
+      # answer refs do (AnswerRefs), not the process's.
+      @kernel.session_cwd = -> { @session&.working_directory }
       @kernel.guardrail_gate = @guardrail_wiring.gate
       # The turn-end warm-up; the kernel asks it for a slot pin per request.
       @prompt_warmup = PromptWarmup.new
@@ -1339,6 +1343,12 @@ module Samagotchi
 
     def session_state_dir = @session_state_dir || Session.default_state_dir
 
+    # The running turn's metrics so far, saved as a turn a worker died in
+    # would leave them (SessionMetrics#persist's running_turn): a worker's
+    # turn checkpoint (TurnCheckpoint) calls it when it writes.
+    # @return [Boolean] whether they were saved
+    def checkpoint_metrics = @metrics.persist(state_dir: session_state_dir, running_turn: true)
+
     # What a Bridge adds to a plugin's ctx.messages while a turn runs (the
     # turn so far, as messages); nil without a Bridge (the REPL).
     attr_writer :running_turn_messages
@@ -1478,19 +1488,31 @@ module Samagotchi
     private :save_quietly
 
     # Keep what the after_turn hooks presented as the answer's `display`
-    # and tell the observers (:answer_display), after the turn_completed
-    # they already had: the web re-reads the answer then. A turn_completed
+    # and the refs they attached as its `display_refs` (AnswerRefs, one
+    # replace for both), and tell the observers (:answer_display, the
+    # display or nil, and how many refs), after the turn_completed they
+    # already had: the web re-reads the answer then. A turn_completed
     # with display_pending (after_turn hooks were about to run) always gets
     # one, `display: nil` when nothing was presented, so the web holds the
     # answer's pop until then and never swaps it after. Terminals are not
     # sinks of it; they printed the answer already. The session is saved by
     # the caller, as after every turn.
-    def store_answer_display(session, display, pending: false)
+    def store_answer_display(session, display, refs, pending: false)
       synchronize_events do
+        # A plugin that kept event[:refs] and calls it later gets nil: the
+        # list is stored now (and the turn is over on every path).
+        refs.close!
         messages = Array(session.messages)
-        if display.changed? && messages.last.equal?(display.target)
-          replace_session_messages(session, messages[0...-1] + [display.target.merge(AnswerDisplay::KEY => display.text)])
-          @session_observer.notify({ type: :answer_display, display: display.text })
+        changed = display.changed? && messages.last.equal?(display.target)
+        added = refs.added? && messages.last.equal?(refs.target)
+        if changed || added
+          merged = messages.last.dup
+          merged[AnswerDisplay::KEY] = display.text if changed
+          merged[AnswerRefs::KEY] = refs.to_a if added
+          replace_session_messages(session, messages[0...-1] + [merged])
+          event = { type: :answer_display, display: changed ? display.text : nil }
+          event[:refs] = refs.count if added
+          @session_observer.notify(event)
         elsif pending
           @session_observer.notify({ type: :answer_display, display: nil })
         end
@@ -2228,15 +2250,18 @@ module Samagotchi
 
       # Fire :after_turn hook (an answer or a Stop; an Interrupt or a failure
       # ends the turn in #run_turn without it), with a read-only
-      # copy of the conversation the turn stored, and event[:present] for
-      # a display version of the answer (AnswerDisplay).
+      # copy of the conversation the turn stored, event[:present] for
+      # a display version of the answer (AnswerDisplay) and event[:refs]
+      # for refs on it (AnswerRefs).
       session = turn.session
       display = AnswerDisplay.new(session.messages)
+      refs = AnswerRefs.new(session.messages, cwd: session.working_directory)
       after_turn = { type: :after_turn, status: canceled ? "canceled" : "completed",
                      messages: hook_messages(session.messages) }
       after_turn[:present] = display.presenter(after_turn)
+      after_turn[:refs] = refs.adder(after_turn)
       @hooks.fire(:after_turn, after_turn)
-      store_answer_display(session, display, pending: display_pending)
+      store_answer_display(session, display, refs, pending: display_pending)
 
       # Fire :session_end after the turn (turn-level lifecycle), as :after_turn
       @hooks.fire(:session_end, { type: :session_end, session_id: session.id })
@@ -2547,6 +2572,19 @@ module Samagotchi
       clone_messages(@session&.messages)
     end
 
+    # The running turn's conversation as its loop builds it (both loops
+    # register it on the kernel's llm_context_turn): the same array the loop
+    # appends to, not a copy, so read it on the turn's thread (the pending
+    # input drain, at an iteration boundary: TurnCheckpoint). nil when no
+    # turn runs (llm_context_turn is never cleared, and still holds the
+    # last turn's then).
+    # @return [Array<Hash>, nil]
+    def live_conversation
+      return nil unless turn_running? && @kernel.respond_to?(:llm_context_turn)
+
+      @kernel.llm_context_turn&.conversation
+    end
+
     # Append messages to the current session's conversation.
     # @param messages [Array<Hash>]
     # @return [Array<Hash>] the session's messages

data/lib/samagotchi/engine_peers.rb

@@ -15,6 +15,7 @@ module Samagotchi
       def project_root = engine.session&.project_root
       def state_dir = engine.peer_state_dir
       def cancelled? = !!engine.active_cancel_controller&.cancelled?
+      def cancel_reason = engine.active_cancel_controller&.reason
       def relay = engine.relay_peer
       def model_ref = engine.effective_model_ref
       def thinking = engine.thinking_override

data/lib/samagotchi/hooks/registry.rb

@@ -253,9 +253,11 @@ module Samagotchi
       #   event[:steer].call(text) -> true when the text was queued for the
       #     running turn's next boundary (its own user message, source: the
       #     hook's bundle); from after_turn / session_end false
-      # and after_turn's fire site adds one more (AnswerDisplay):
+      # and after_turn's fire site adds two more (AnswerDisplay, AnswerRefs):
       #   event[:present].call { |text| new_text } -> the answer's display
       #     text after the call (chained in hook order), nil without an answer
+      #   event[:refs].call(match:, kind:, target:, label: nil, actions: [])
+      #     -> true (kept), false (refused, logged), nil without an answer
       #
       # @param name [Symbol] the hook name to fire
       # @param event [Hash] the event payload (may be mutated by hooks)

data/lib/samagotchi/interrupted_turn.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The mark of a turn a worker checkpointed and never finished
+  # (Session#interrupted_turn, saved as session.json's "interrupted_turn"):
+  # TurnCheckpoint writes it with the turn's messages so far while the turn
+  # runs; the turn's end saves without it; the next worker to start finds it
+  # and settles the turn (Worker#settle_interrupted_turn).
+  #
+  # id: the turn's id (nil when unknown); started_at / at: iso8601, when the
+  # turn began and when this checkpoint was taken; iteration: the loop
+  # boundaries it had passed (Integer).
+  InterruptedTurn = Data.define(:id, :started_at, :at, :iteration) do
+    def initialize(id: nil, started_at: nil, at: nil, iteration: nil) = super
+
+    # A saved record (string or symbol keys), an InterruptedTurn as it is;
+    # nil for anything else.
+    # @return [InterruptedTurn, nil]
+    def self.from_file(raw)
+      return raw if raw.is_a?(InterruptedTurn)
+      return nil unless raw.is_a?(Hash)
+
+      new(**members.to_h { |m| [m, raw.key?(m.to_s) ? raw[m.to_s] : raw[m]] })
+    end
+
+    # @return [Hash{String => Object}] string keys, unset fields left out
+    def to_file = to_h.compact.transform_keys(&:to_s)
+
+    # Seconds from the turn's start to this checkpoint (nil when unknown).
+    # @return [Float, nil]
+    def seconds
+      return nil unless started_at && at
+
+      (Time.iso8601(at) - Time.iso8601(started_at)).clamp(0, Float::INFINITY)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/samagotchi/kernel_loop.rb

@@ -18,6 +18,7 @@ require_relative "thinking"
 require_relative "hooks"
 require_relative "pending_input_queue"
 require_relative "steer"
+require_relative "reasoning_history"
 require_relative "thought_stream_splitter"
 require_relative "tools/builtins"
 require_relative "muted_memories"
@@ -172,6 +173,10 @@ module Samagotchi
     #   too); the thinking level is its own field, since the native path
     #   sends the sampling as is.
     attr_accessor :turn_settings
+    # The session's working directory (a callable → String or nil), which
+    # a plugin tool's row refs resolve their files against (ToolRunner,
+    # RowRefs); the Engine sets it. nil: the process's own (Dir.pwd).
+    attr_accessor :session_cwd
     # Tools::Peers (or the Engine's live view of it): the session
     # list_sessions and send_note speak for; nil outside a session.
     attr_accessor :peers
@@ -291,7 +296,7 @@ module Samagotchi
     private_constant :Turn, :Request, :Generation
 
     def start_turn(messages, on_stream_event:, cancel_controller:, pending_input:, cap:, reasoning_since: nil)
-      conversation = prepare_conversation(messages, keep_thought_from: thought_floor(messages, reasoning_since))
+      conversation = prepare_conversation(messages, keep_thought_from: ReasoningHistory.run_start(messages, reasoning_since))
       context = ContextStatus.new(conversation: conversation, llm_context: @turn_settings.llm_context)
       emit = ->(event) { emit_stream_event(on_stream_event, event) }
       @llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: context, emit: emit)
@@ -1003,11 +1008,13 @@ module Samagotchi
     def sanitize_history(messages, keep_thought_from: nil)
       messages.each_with_index.map do |m, index|
         if m[:role] == "model" && keep_thought_from && index >= keep_thought_from
-          { role: m[:role], content: m[:content].to_s, display: m[:display] }.compact
+          { role: m[:role], content: m[:content].to_s, display: m[:display], display_refs: m[:display_refs] }.compact
         elsif m[:role] == "model"
-          # `display` rides along so the stored conversation keeps it; the
-          # prompt formatter never reads it (AnswerDisplay).
-          { role: m[:role], content: strip_thought_blocks(m[:content].to_s), display: m[:display] }.compact
+          # `display` and `display_refs` ride along so the stored
+          # conversation keeps them; the prompt formatter never reads them
+          # (AnswerDisplay, AnswerRefs).
+          { role: m[:role], content: strip_thought_blocks(m[:content].to_s), display: m[:display],
+            display_refs: m[:display_refs] }.compact
         else
           m.dup
         end
@@ -1015,24 +1022,10 @@ module Samagotchi
     end
 
     # Standard multi-turn compliance: never pass prior raw thought blocks,
-    # but a resumed run's (+keep_thought_from+, #thought_floor): the same
+    # but a resumed run's (+keep_thought_from+, ReasoningHistory.run_start): the same
     # run going on after a step-limit Continue.
     def prepare_conversation(messages, keep_thought_from: nil) = sanitize_history(messages, keep_thought_from: keep_thought_from)
 
-    # Where a resumed run's thought blocks start: its start (+since+). Inside
-    # one native run nothing re-sanitizes, so a user entry the run merged (a
-    # steer, a delegate report, the Qwen recovery prompt) left the thoughts
-    # before it in the prompt: they stay. Only a user or turn_start entry
-    # added after the run ended (after its last model message: a !cmd's
-    # output) starts them again past itself. nil without +since+.
-    def thought_floor(messages, since)
-      return nil if since.nil?
-
-      last_reply = messages.rindex { |m| m[:role].to_s == "model" } || -1
-      query = messages.rindex { |m| m[:role].to_s == "user" || m[:turn_start] == true }
-      query && query > last_reply ? [query + 1, since].max : since
-    end
-
     def duplicate_conversation(messages)
       messages.map(&:dup)
     end