samagotchi 0.2.0 → 0.4.0

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

@@ -0,0 +1,531 @@
+# frozen_string_literal: true
+
+# Loaded through module_eval: it requires what it uses.
+require "open3"
+
+# 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
+# web, each ref in the answer becomes a link (`[JIRA-123](https://…)`,
+# through event[:present]: display only, the model's text stays as it was,
+# and it survives a reload). Every UI also gets one line right after the
+# turn, the terminals' only view of the links:
+#
+#   sources: JIRA JIRA-123 → https://myjira.com/browse/JIRA-123, JIRA JIRA-10 → https://myjira.com/browse/JIRA-10
+#
+# Sources are configured patterns (config.yml, `bundles: source-links:`),
+# so JIRA is just the first entry; any source can be added:
+#
+#   bundles:
+#     source-links:
+#       sources:
+#         - name: JIRA
+#           prefix: JIRA              # simple form: \bJIRA-(\d+)\b
+#           base_url: https://myjira.com/browse/
+#         - name: GitHub
+#           pattern: '\bGH-(\d+)\b'   # full form: a regex
+#           url: 'https://github.com/org/repo/issues/{match}'
+#           case_insensitive: false   # optional, default false
+#         - 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'
+#           url: 'https://github.com/{repo}/issues/{num}'
+#           remote: origin            # optional: the git remote {repo}/{host}
+#                                     # come from, default origin
+#           remote_host: github.com   # optional: a host or a list; else a
+#                                     # remote on another host links nothing
+#       max: 10                       # optional: refs per line, default 10
+#       note: false                   # optional: no sources line (the web
+#                                     # links stay), default true
+#
+# A `url:` template takes {match} (group 1, else the whole ref), {1}…{9}
+# (numbered groups), {name} (named groups), and {repo}/{host}: the named
+# group when it took part, else the project's (Dir.pwd's) git remote, asked
+# of git once per worker. A ref with a placeholder that can't be filled is
+# not linked; a `{word}` that is none of these stays text (warned at load).
+#
+# The note is not stored in the conversation: it is an event, replayed by a
+# UI only while the session's worker lives (a reload keeps it; a stopped
+# worker loses it). The links are stored as the answer's display. A ref in
+# code (a `span` or a fenced block) or in a markdown link is not linked in
+# the answer. The hook is inert until sources are configured.
+class SourceLinks
+  # The answer is scanned only up to this many characters: the primary
+  # ReDoS guard, bounding the input a user-supplied regex can chew on.
+  MAX_SCAN = 20_000
+  # Refs per line before the "… +N more" tail.
+  DEFAULT_MAX = 10
+  # Per-regex timeout (Ruby 3.2+): a catastrophic pattern is abandoned
+  # instead of hanging the turn. No global Regexp.timeout is touched. The
+  # timeout is per match attempt, not per scan; MAX_SCAN bounds the total.
+  REGEX_TIMEOUT = 0.5
+  # A bare URL (scheme-anchored, so it can't start inside a markdown label),
+  # and a markdown link (label in group 1, target in group 2).
+  URL_SPAN = %r{[a-z][a-z0-9+.\-]*://\S+}i
+  MARKDOWN_LINK = /\[([^\]]*)\]\(([^)]*)\)/
+  # A fenced code block's opening line (up to 3 spaces, then ``` or ~~~).
+  FENCE_OPEN = /\A {0,3}(`{3,}|~{3,})/
+  # A `{word}` or `{N}` placeholder in a `url:` template.
+  PLACEHOLDER = /\{(\w+)\}/
+  # 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
+  # `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
+  # `.` is a local path.
+  REMOTE_SCP = %r{\A(?:[^@/:]+@)?([^/:.@][^/:@]*):(.*)\z}
+
+  # The {host:, repo:} a git remote URL names, or nil (a local path,
+  # `file://`, an empty path, or a path with an empty or dot segment).
+  def self.parse_remote_url(url)
+    url = url.to_s.strip
+    # Any other scheme (file://, a transport helper's) is not a web host.
+    match = url.include?("://") ? url.match(REMOTE_URL) : url.match(REMOTE_SCP)
+    return nil unless match
+
+    host = match[1]
+    repo = match[2].to_s.sub(%r{\A/+}, "").sub(%r{/+\z}, "").sub(/\.git\z/, "").sub(%r{/+\z}, "")
+    segments = repo.split("/", -1)
+    return nil if host.empty? || segments.empty? || segments.any? { |segment| ["", ".", ".."].include?(segment) }
+
+    { host: host, repo: repo }
+  end
+
+  def initialize(settings = {})
+    settings = {} unless settings.is_a?(Hash)
+    @sources = compile_sources(settings["sources"])
+    max = settings["max"].to_i
+    @max = max.positive? ? max : DEFAULT_MAX
+    @note = settings["note"] != false
+    # [Dir.pwd, remote name] => {host:, repo:} or nil, for the worker's life.
+    @remotes = {}
+    @host_mismatch_logged = {}
+  end
+
+  def call(event)
+    return unless event.is_a?(Hash) && event[:type] == :after_turn
+    return unless event[:status].to_s == "completed"
+    return if @sources.empty?
+
+    text = last_model_text(event[:messages])
+    return if text.nil? || text.empty?
+
+    hits = occurrences(text[0, MAX_SCAN])
+    if @note
+      found = collect(hits)
+      event[:notify]&.call(line(found), level: :info) unless found.empty?
+    end
+    # The answer as shown: the model's text unless an earlier hook changed
+    # it (then its offsets differ, so it is scanned again).
+    event[:present]&.call { |shown| link(shown, shown == text ? hits : nil) }
+  end
+
+  private
+
+  # 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
+  # check alone is enough.
+  def last_model_text(messages)
+    Array(messages).reverse_each do |message|
+      next unless message.is_a?(Hash)
+      next unless (message.key?(:role) ? message[:role] : message["role"]).to_s == "model"
+
+      content = message.key?(:content) ? message[:content] : message["content"]
+      return content.to_s
+    end
+    nil
+  end
+
+  # Every ref the note may name, as {start:, finish:, name:, ref:, url:,
+  # quiet:}, by offset (whatever order the sources are configured in). The
+  # skip rules below drop a ref that is already a link; +quiet+ marks one
+  # the note names but the answer does not link (in code, or in a markdown
+  # link's label: a link can't hold another). A source whose regex times out
+  # is skipped whole: its partial matches are discarded, the others still
+  # report.
+  def occurrences(text)
+    url_spans = bare_url_spans(text)
+    links = markdown_links(text)
+    code = code_spans(text)
+    labels = links.map { |link| link[:label] }
+    found = []
+    @sources.each do |source|
+      hits = []
+      begin
+        text.scan(source[:regex]) do
+          match = Regexp.last_match
+          start = match.begin(0)
+          finish = match.end(0)
+          next if inside_any?(url_spans, start, finish)
+          next if inside_markdown_link?(links, text, match)
+          next if url_adjacent?(text, match)
+
+          # An unresolved placeholder: no link, from this source.
+          url = source[:url].call(match[0], match)
+          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 }
+        end
+      rescue Regexp::TimeoutError
+        Samagotchi::Log.warn(:hooks, "source_links_timeout",
+                             echo: "[samagotchi:hooks] source-links: #{source[:name]} timed out; skipped")
+        next
+      end
+      found.concat(hits)
+    end
+    # By offset; on a tie (two sources on one ref) the first configured wins.
+    found.each_with_index.sort_by { |hit, index| [hit[:start], index] }.map(&:first)
+  end
+
+  # [name, ref, url] for the note: first-occurrence order, deduped by the
+  # URL case-insensitively (`#12` and `o/r#12` may name one issue; with
+  # case_insensitive, `JIRA-1` and `jira-1` are one ticket).
+  def collect(hits)
+    seen = {}
+    hits.filter_map do |hit|
+      key = hit[:url].downcase
+      next if seen.key?(key)
+
+      seen[key] = true
+      [hit[:name], hit[:ref], hit[:url]]
+    end
+  end
+
+  # +text+ with each ref as a markdown link, every occurrence; the part
+  # beyond MAX_SCAN stays as it is. +hits+ are the scan of that text when
+  # the caller has it.
+  def link(text, hits = nil)
+    head = text[0, MAX_SCAN]
+    hits ||= occurrences(head)
+    out = +""
+    pos = 0
+    hits.each do |hit|
+      next if hit[:quiet] || hit[:start] < pos # two sources on one ref: the first wins
+
+      out << head[pos...hit[:start]] << "[#{hit[:ref].gsub(/[\[\]]/) { |c| "\\#{c}" }}](#{link_target(hit[:url])})"
+      pos = hit[:finish]
+    end
+    return text if pos.zero?
+
+    out << head[pos..] << text[MAX_SCAN..].to_s
+  end
+
+  # A URL as a markdown link target: whitespace and what would end it
+  # (parentheses, angle brackets) percent-encoded.
+  def link_target(url)
+    url.gsub(/[\s()<>]/) { |c| c.bytes.map { |b| format("%%%02X", b) }.join }
+  end
+
+  # The [start, end) ranges of the answer that are code: fenced blocks
+  # (``` or ~~~, to the closing fence or the end) and inline spans (a run
+  # of backticks to the next run of the same length). A line walk and a
+  # lookup per backtick run, no regex over the whole answer.
+  def code_spans(text)
+    fences = fenced_blocks(text)
+    runs = []
+    text.scan(/`+/) { runs << [Regexp.last_match.begin(0), Regexp.last_match.end(0)] }
+    runs.reject! { |start, finish| inside_any?(fences, start, finish) }
+    by_length = Hash.new { |hash, key| hash[key] = [] }
+    runs.each_with_index { |(start, finish), index| by_length[finish - start] << index }
+    spans = []
+    index = 0
+    while index < runs.size
+      start, finish = runs[index]
+      same = by_length[finish - start]
+      closing = same.bsearch { |other| other > index }
+      if closing
+        spans << [start, runs[closing][1]]
+        index = closing + 1
+      else
+        index += 1
+      end
+    end
+    fences + spans
+  end
+
+  def fenced_blocks(text)
+    blocks = []
+    open = nil
+    offset = 0
+    text.each_line do |line|
+      marker = line[FENCE_OPEN, 1]
+      if open.nil? && marker
+        open = [offset, marker]
+      elsif open && marker && marker[0] == open[1][0] && marker.length >= open[1].length && line.strip == marker
+        blocks << [open[0], offset + line.length]
+        open = nil
+      end
+      offset += line.length
+    end
+    blocks << [open[0], text.length] if open
+    blocks
+  end
+
+  # The [start, end) character ranges of the answer that are a bare URL
+  # (scheme-anchored, `[a-z][a-z0-9+.\-]*://\S+`). A ref inside one is not
+  # linked again. The span stops at the first `)` that no `(` inside the URL
+  # balances — so `(https://x.com/a)` ends before the `)`, while
+  # `…/Foo_(bar)` keeps it.
+  def bare_url_spans(text)
+    spans = []
+    text.scan(URL_SPAN) do
+      match = Regexp.last_match
+      finish = trim_url_end(match[0], match.begin(0), match.end(0))
+      spans << [match.begin(0), finish] if finish > match.begin(0)
+    end
+    spans
+  end
+
+  # The end offset of a URL match after trimming its tail: the span stops at
+  # the first `)` that no `(` inside the URL balances.
+  def trim_url_end(url, start, finish)
+    depth = 0
+    url.each_char.with_index do |char, index|
+      if char == "("
+        depth += 1
+      elsif char == ")"
+        if depth.zero?
+          finish = start + index
+          break
+        end
+        depth -= 1
+      end
+    end
+    finish
+  end
+
+  # A markdown link's label and target ranges, with the target text. A ref in
+  # the target is a link destination (skip it); a ref in the label is skipped
+  # only when the target names that same ref — `[JIRA-123](https://x.com/JIRA-123)`
+  # is skipped, while `[fix for JIRA-123](https://github.com/o/r/pull/9)` still
+  # links the ticket.
+  def markdown_links(text)
+    links = []
+    text.scan(MARKDOWN_LINK) do
+      match = Regexp.last_match
+      links << { label: [match.begin(1), match.end(1)],
+                 target: [match.begin(2), match.end(2)],
+                 target_text: match[2].to_s }
+    end
+    links
+  end
+
+  def inside_any?(spans, start, finish)
+    spans.any? { |span_start, span_end| start >= span_start && finish <= span_end }
+  end
+
+  def inside_markdown_link?(links, text, match)
+    start = match.begin(0)
+    finish = match.end(0)
+    links.any? do |link|
+      in_target = start >= link[:target][0] && finish <= link[:target][1]
+      in_label = start >= link[:label][0] && finish <= link[:label][1]
+      in_target || (in_label && target_names_ref?(link[:target_text], text[start...finish]))
+    end
+  end
+
+  # True when the link target names the ref as a whole token: the lookarounds
+  # reject a ref character (letter, digit or `-`) immediately before or after
+  # the ref. So `[JIRA-1](…/JIRA-12)` is NOT skipped (the target names
+  # JIRA-12), while `[JIRA-123](…/JIRA-123)` is. Note this is stricter than
+  # the bare-text scan's `\b`, which treats `-` as a boundary: `…/JIRA-1-foo`
+  # would match there but not here.
+  def target_names_ref?(target, ref)
+    escaped = Regexp.escape(ref)
+    target.match?(/(?<![A-Za-z0-9\-])#{escaped}(?![A-Za-z0-9\-])/)
+  end
+
+  # A ref glued to URL punctuation is part of a link too, even when the span
+  # scan misses it: `/browse/JIRA-1`, `?key=JIRA-1`, `JIRA-1/foo`. The
+  # character right before is `/`, `=` or `?`, or the one right after is `/`.
+  # `:` and `#` are NOT here: `Ticket:JIRA-5` and `#JIRA-123` are ordinary
+  # plain-text ways to write a ticket, and a real URL is caught by the span
+  # scan anyway.
+  def url_adjacent?(text, match)
+    start = match.begin(0)
+    before = start.positive? ? text[start - 1] : nil
+    after = text[match.end(0)]
+    ["/", "=", "?"].include?(before) || after == "/"
+  end
+
+  def line(found)
+    shown = found.first(@max)
+    text = "sources: #{shown.map { |name, ref, url| "#{name} #{ref} → #{url}" }.join(', ')}"
+    extra = found.size - shown.size
+    text += ", … +#{extra} more" if extra.positive?
+    text
+  end
+
+  def compile_sources(raw)
+    Array(raw).filter_map { |entry| compile_source(entry) }
+  end
+
+  # One configured source as {name:, regex:, url:}, or nil (with a warn) for
+  # an entry that is not a mapping, names neither a prefix nor a pattern, or
+  # whose pattern does not compile. Never raises into the turn.
+  def compile_source(entry)
+    unless entry.is_a?(Hash)
+      warn_invalid("a source entry must be a mapping, not #{entry.class}")
+      return nil
+    end
+
+    entry = entry.transform_keys(&:to_s)
+    name = entry["name"].to_s.strip
+    prefix = entry["prefix"].to_s.strip
+    pattern = entry["pattern"].to_s
+    flags = entry["case_insensitive"] ? Regexp::IGNORECASE : 0
+
+    if !prefix.empty?
+      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}" } }
+    elsif !pattern.empty?
+      name = "source" if name.empty?
+      regex = Regexp.new(pattern, flags, timeout: REGEX_TIMEOUT)
+      template = entry["url"].to_s
+      known = known_placeholders(name, template, regex)
+      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.merge(regex: regex, url: ->(ref, match) { render_url(template, known, match, ref, source) })
+    else
+      warn_invalid("a source needs a prefix: or a pattern:")
+      nil
+    end
+  rescue RegexpError => e
+    warn_invalid("its pattern does not compile: #{e.message}")
+    nil
+  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.
+  def known_placeholders(name, template, regex)
+    used = template.scan(PLACEHOLDER).flatten.uniq
+    groups = group_count(regex)
+    known, unknown = used.partition do |word|
+      if word.match?(/\A\d+\z/)
+        groups.nil? || (word.to_i.between?(1, groups))
+      else
+        BUILTIN_PLACEHOLDERS.include?(word) || regex.names.include?(word)
+      end
+    end
+    unless unknown.empty?
+      list = unknown.map { |word| "{#{word}}" }.join(", ")
+      Samagotchi::Log.warn(:hooks, "source_links_unknown_placeholder",
+                           echo: "[samagotchi:hooks] source-links: #{name}: #{list}: no such group in its pattern; " \
+                                 "left as text")
+    end
+    known
+  end
+
+  # How many groups +regex+ captures (with named groups, only those), found
+  # by matching an always-empty alternative; nil when that fails.
+  def group_count(regex)
+    probe = Regexp.new("(?:#{regex.source}\n)|", regex.options, timeout: REGEX_TIMEOUT)
+    probe.match("").size - 1
+  rescue RegexpError, Regexp::TimeoutError
+    nil
+  end
+
+  # The URL for one hit: +template+ with its +known+ placeholders filled, or
+  # nil when one can't be (a group that didn't take part, a {repo} with an
+  # empty or dot segment, no remote): we never build a URL with a hole.
+  def render_url(template, known, match, ref, source)
+    unresolved = false
+    url = template.gsub(PLACEHOLDER) do
+      word = Regexp.last_match(1)
+      next Regexp.last_match(0) unless known.include?(word)
+
+      value = placeholder_value(word, match, ref, source)
+      unresolved = true if value.nil?
+      value.to_s
+    end
+    unresolved ? nil : url
+  end
+
+  # One placeholder's escaped value, or nil when it is unresolved.
+  def placeholder_value(word, match, ref, source)
+    case word
+    when "match" then escape_url(match[1] || ref)
+    when /\A\d+\z/ then match[word.to_i]&.then { |value| escape_url(value) }
+    when "repo", "host"
+      value = match.names.include?(word) ? match[word] : nil
+      value ||= remote_value(word, source)
+      word == "repo" ? escape_repo(value) : value&.then { |host| escape_url(host) }
+    else match[word]&.then { |value| escape_url(value) }
+    end
+  end
+
+  # {repo} / {host} from the project's git remote (the source's `remote:`,
+  # default origin); nil when there is none, or when its host is not one of
+  # the source's `remote_host:` list.
+  def remote_value(word, source)
+    remote = project_remote(source[:remote])
+    return nil unless remote
+
+    hosts = source[:remote_hosts]
+    unless hosts.empty? || hosts.include?(remote[:host].downcase)
+      key = [source[:name], remote[:host]]
+      unless @host_mismatch_logged[key]
+        @host_mismatch_logged[key] = true
+        Samagotchi::Log.debug(:hooks, "source_links_remote_host_mismatch", source: source[:name],
+                                                                          host: remote[:host], remote_host: hosts.join(","))
+      end
+      return nil
+    end
+    remote[word.to_sym]
+  end
+
+  # The project's (Dir.pwd's) remote +name+ as {host:, repo:}, or nil.
+  # Asked of git lazily (only a hit that needs it) and remembered, nil too,
+  # per [Dir.pwd, name]: git applies insteadOf rewrites and includes, and a
+  # worktree reports its main repo's remote.
+  def project_remote(name)
+    key = [Dir.pwd, name]
+    return @remotes[key] if @remotes.key?(key)
+
+    @remotes[key] = read_remote(key[0], name)
+  end
+
+  def read_remote(dir, name)
+    out, status = Open3.capture2({ "GIT_DIR" => nil, "GIT_WORK_TREE" => nil },
+                                 "git", "-C", dir, "remote", "get-url", name, err: File::NULL)
+    unless status.success?
+      Samagotchi::Log.debug(:hooks, "source_links_no_remote", remote: name, exit: status.exitstatus)
+      return nil
+    end
+    remote = self.class.parse_remote_url(out)
+    Samagotchi::Log.debug(:hooks, "source_links_remote", remote: name, host: remote&.dig(:host), repo: remote&.dig(:repo))
+    remote
+  rescue SystemCallError => e
+    Samagotchi::Log.debug(:hooks, "source_links_no_remote", remote: name, error: e.class.name)
+    nil
+  end
+
+  # A repo path with each `/`-separated segment escaped and the `/` kept
+  # (GitLab's `group/sub/proj`); nil for an empty, `.` or `..` segment, which
+  # a browser would resolve out of the path.
+  def escape_repo(value)
+    return nil if value.nil?
+
+    segments = value.split("/", -1)
+    return nil if segments.empty? || segments.any? { |segment| ["", ".", ".."].include?(segment) }
+
+    segments.map { |segment| escape_url(segment) }.join("/")
+  end
+
+  def warn_invalid(reason)
+    Samagotchi::Log.warn(:hooks, "source_links_invalid_source",
+                         echo: "[samagotchi:hooks] source-links: skipping a source: #{reason}")
+  end
+
+  # A capture group is free-form, so escape what goes into the URL path.
+  def escape_url(value)
+    value.to_s.gsub(%r{[^A-Za-z0-9\-._~]}) { |c| c.bytes.map { |b| format("%%%02X", b) }.join }
+  end
+end

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

@@ -0,0 +1,14 @@
+---
+name: source-links
+version: 0.3.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
+files:
+  source_links.md: sha256:aebd37f1e25491780994ecc4afc20ed6e8db32b724dc038302bb050177efada8
+hooks:
+  source_links.rb:
+    sha256: sha256:0ee86a932efc90d81777855c81dea16510710d7371fe8b6b146a5a16b29794c2
+    event: after_turn
+    on_error: log
+    priority: 90

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

@@ -0,0 +1,5 @@
+# Source links
+
+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, which every UI shows (the terminals only see this line). 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 while the session's worker lives (a page reload keeps it; a stopped worker loses it).
+
+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.

data/lib/samagotchi/bundles/system/config_modification_protocol.md

@@ -18,7 +18,7 @@ Single registry `Samagotchi::Config` (`Config::ENTRIES` in `lib/samagotchi/confi
 
 Sections forbid `_`/`-` (`SECTION_RE` `/\A[a-z0-9]+\z/`); leaves keep `snake_case` in YAML (`base_url`) and become kebab in CLI (`base-url`) via registry derivation — no generic string split, registry lookup avoids flat vs nested collision.
 
-**Universal entries** (`expose: [:env,:config,:cli]`): `default.model`, `server.host/port/transport/open_timeout/read_timeout`, `server.first_token_timeout` (env and config only), `recap.model/base_url/host_ref/inactivity/timeout/min_user_turns/sentences`, `session.retention_days/max_count/keep_status/sweep_interval_hours/idle_exit_minutes`, `session.shared/keep_empty/max_children` (env and config only), `log.file/disable`, `status.line/width_mode/max_width/fixed_width`, `context.status/window_tokens/chars_per_token/status_thresholds/status_cadence`, `thinking.ui/preview_lines/render_interval`, `n_predict`, `max_tool_output_chars`, `retry.max/base_delay/max_delay`, `read.*`, `execute.*`, `web.port/host`, `no_interrupt`, `no_default_input` etc. (`Config::ENTRIES`; `expose` says which of env/config/cli each takes). Precedence is `CLI > ENV > file > default`.
+**Universal entries** (`expose: [:env,:config,:cli]`): `default.model`, `server.host/port/transport/open_timeout/read_timeout`, `server.first_token_timeout` (env and config only), `recap.model/base_url/host_ref/inactivity/timeout/min_user_turns/sentences`, `session.retention_days/max_count/keep_status/sweep_interval_hours/idle_exit_minutes`, `session.shared/keep_empty/max_children` (env and config only), `log.file/disable`, `status.line/width_mode/max_width/fixed_width`, `context.status/window_tokens/chars_per_token/status_thresholds/status_cadence`, `thinking.ui/render_interval/turn_preamble`, `default.n_predict`, `max_tool_output_chars`, `retry.max/base_delay/max_delay`, `read.*`, `execute.*`, `web.port/host`, `no_interrupt`, `no_default_input` etc. (`Config::ENTRIES`; `expose` says which of env/config/cli each takes). Precedence is `CLI > ENV > file > default`.
 
 Example `config.yml` (new nested form, preferred):
 
@@ -52,13 +52,13 @@ log:
   disable: false
 ```
 
-Legacy flat keys (`SAMAGOTCHI_DEFAULT_MODEL`, `SAMAGOTCHI_N_PREDICT` etc. at top-level) are still read via fallback in `Config.lookup_yaml` but warn `Warning: config key 'SAMAGOTCHI_DEFAULT_MODEL' is legacy UPPER — use 'default.model'` (`ConfigFile.load_global_env!`). Migrate them to nested form and remove the flat entry. The old `LLAMA_HOST`/`LLAMA_PORT` aliases were removed; use `server.host`/`server.port` (nested) or `SAMAGOTCHI_SERVER_HOST`/`SAMAGOTCHI_SERVER_PORT`.
+Legacy flat keys (`SAMAGOTCHI_DEFAULT_MODEL`, `SAMAGOTCHI_N_PREDICT` etc. at top-level) are still read via fallback in `Config.lookup_yaml` but warn `Warning: config key 'SAMAGOTCHI_DEFAULT_MODEL' is legacy UPPER — use 'default.model'` (`ConfigFile.load_global_env!`). When a file has both, the nested key wins and the warning names both. Migrate them to nested form and remove the flat entry. The old `LLAMA_HOST`/`LLAMA_PORT` aliases were removed; use `server.host`/`server.port` (nested) or `SAMAGOTCHI_SERVER_HOST`/`SAMAGOTCHI_SERVER_PORT`.
 
 **Excluded maps** (YAML-only, not part of the flat registry; skipped by scalar loader):
 
 - `model_aliases:` map of alias → model id (`ConfigFile.resolve_model_alias`). Keys lowercased on write (`ConfigFile.write_model_alias!`). Values may be bare `model` or qualified `host:model` (hybrid).
-- `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, enabled}` (`ConfigFile.hosts_config`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `transport` overrides `server.transport`; `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; workers inherit via `SAMAGOTCHI_HOSTS_JSON` (`hosts_json_for_env`, `session_manager.rb`).
-- `models:` map of model id or alias → `{profile}` (`ConfigFile.model_settings`). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name on mlx, which has no template to read).
+- `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, vision, sampling, thinking, enabled}` (`ConfigFile.hosts_config`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `transport` overrides `server.transport`; `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; workers inherit via `SAMAGOTCHI_HOSTS_JSON` (`hosts_json_for_env`, `session_manager.rb`).
+- `models:` map of model id or alias → `{profile, vision, sampling, thinking}` (`ConfigFile.model_settings`). `thinking:` (here, on a host, or `thinking.level` for every model) is `off|low|medium|high|default` (`Thinking`; unquoted `off` works, `on` is not a level; `default` = send nothing). Precedence: `--thinking`/`SAMAGOTCHI_THINKING_LEVEL` > `models:` > `hosts.<name>.thinking` > `thinking.level` in config.yml > `default`. A `sampling:` key wins over the fields a level sends (`null` drops one); `docs/configuration.md` "Thinking". `sampling:` (here or on a host) is a map of request fields passed to the provider as written (`temperature`, `top_p`, `presence_penalty`, `repeat_penalty`, …; a model's fields win over its host's per field; `null` = don't send; chi's own fields like `max_tokens`/`stream` are refused with a warning; `docs/configuration.md` "Sampling"). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name on mlx, which has no template to read).
 - `hooks:` map of `hooks_dir` + per-event lists `{path, on_error}` (`Hooks::Loader.load`). `hooks_dir` may start with `~`.
 - `guardrails:` tool-call rules (`docs/guardrails.md`; read in `Engine#guardrail_rules`, parsed by `Guardrails::Rules.parse`): `enabled` (bool, default true; `false` drops rules and hooks' asks, a deny still applies; env `SAMAGOTCHI_GUARDRAILS_ENABLED`), `rules:` (list), `disable:` (list of rule ids, `id` or `bundle:id`, switching off a bundle's or config rule without editing it). A rule takes only `id`, `tool`, `command`, `path`, `verdict`, `reason`, `scopes`: `id` required; at least one of `tool` (a name, `shell` = execute + task_create, a `File.fnmatch` glob like `"mcp_*"`, or a list), `command` (a Ruby regex on the shell command), `path` (a glob, or `outside_repo`); `verdict` `ask|deny`; `scopes` (for `ask`) a subset of `once, session, repo, rule`. **Any parse error (an unknown key, a bad regex, no verdict) makes chi deny every tool call** until fixed, so validate with `YAML.safe_load` and keep the list shape. Rules load when a session starts: restart the worker/REPL after an edit. Installed bundles' rule files (`chi bundle install guardrails`) add to them; `/guardrails` lists what loaded.
 
@@ -92,6 +92,10 @@ bundles:
     deny_after: 2              # same call + same result N times in a turn -> deny the next
     stop_after: 4              # stop the turn at this many denies
     mode: deny                 # deny | notify (warn only); ignore_tools: [task_wait, ...]
+  check-in:
+    after: 50                  # tool calls in one turn with no answer before the first check
+    every: 50                  # then again every N more
+    mode: ask                  # ask (a card) | nudge (nudge the model by itself) | notify; message:, ignore_tools: [...]
   mcp:                         # tools become mcp_<server>_<tool>; /mcp lists them
     timeout: 60                # per call, seconds; startup_timeout: 10
     servers:
@@ -113,7 +117,7 @@ A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cov
 1. **Read** the current file via `read` tool (or `ConfigFile.global_path`). If `File.file?` false, start from `{}`.
 2. `YAML.safe_load` (permitted_classes: [], aliases: false). If data nil or not Hash, treat as `{}` or raise with path.
 3. Mutate the intended **nested** key in the raw hash. Preserve all other keys byte-for-byte where possible. Example for default model: `raw_data["default"] ||= {}; raw_data["default"]["model"] = "new-model"; raw_data.delete("SAMAGOTCHI_DEFAULT_MODEL")` to migrate legacy.
-4. **Validate** (see below) before writing. Also run `Samagotchi::Config.validate_yaml_sections` — it rejects top-level `_` (suggest `default.model`) and warns on legacy flat keys.
+4. **Validate** (see below) before writing. Also run `Samagotchi::Config.validate_yaml_sections` — it returns one `config: unknown key '…' (did you mean '…'?)` per key chi doesn't read (every config-exposed `Config::ENTRIES` key is known as written, including the section-less `max_tool_output_chars` and `skip_agent_md`; names under `hosts:`/`models:`/`model_aliases:`/`hooks:`/`bundles:`/`memories:` are free-form, host and model entries are checked against `Config::MAP_ENTRY_KEYS`). An empty list means no warning at start.
 5. **Write atomically**: `FileUtils.mkdir_p(File.dirname(path))`, `File.write("#{path}.tmp", YAML.dump(raw_data))`, `File.rename("#{path}.tmp", path)`.
 6. Update in-process state: `write_default_model!` sets `ENV["SAMAGOTCHI_DEFAULT_MODEL"]` and `Samagotchi::Config.reload!`; otherwise the harness picks it up on next `Config.get` (live resolve) or restart. CLI overrides (`--default-model`) win over file until process exit.
 
@@ -132,7 +136,7 @@ A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cov
 - **Hosts**: each entry needs `host`, `port` 1-65535, `transport` and `api` optional (a raw `api` must match `transport`), name must match `/\A[a-z0-9][a-z0-9._-]*\z/i`.
 - **Hooks**: each entry must have `path` (relative to `hooks_dir`), `on_error` is `skip` (default) or `log`. Class name must match file basename snake→Pascal.
 - **Scalars via registry**: `Config.coerce` validates `String/Numeric/true/false` per `type: :string/:integer/:float/:bool/:enum`; invalid values warn and fall back to entry `default`.
-- **Sections**: `validate_yaml_sections` rejects top-level keys containing `_` (suggest dotted) and section names containing `_`/`-`.
+- **Keys**: `validate_yaml_sections` flags unknown keys (with a suggestion), a registry section that isn't a mapping, and env/CLI-only keys (`model.profile`).
 
 ## Tools to use
 

data/lib/samagotchi/bundles/system/delegated.md

@@ -1,10 +1,9 @@
 # Delegated session
 
-A parent session delegated your task and reads only your final reply; the user may be watching or not.
+Another chi session (the parent) gave you this task. It reads only your last message of each turn; the user may be watching, or not.
 
-- Do the task; put everything the parent needs in your last message (findings, paths, commands run, what is unverified). Nothing else of yours reaches it.
-- Don't delegate further, don't start other chi sessions, don't send notes to sessions other than the parent.
-- Don't write memories unless the task asks for it; put what you learned in the reply instead.
-- Don't change config, install bundles or edit managed files.
-- Stay in the working directory you were started in.
-- If you are blocked, say so in the reply with the exact question; only ask_user_question when the task says the user is watching.
+- Finish the task in this turn if you can. End with one reply the parent can act on without asking back: the result first, then evidence (paths, commands run and what they printed), then anything you could not verify or finish.
+- The parent may send follow-up messages later; each one is a new turn in this same session, with what you did so far.
+- Work in the directory you were started in. Don't change config, install bundles, edit managed files or write memories unless the task asks for it.
+- You can't delegate further. Don't start other chi sessions, and send notes only to the parent.
+- If you are blocked, stop and say so in the reply with the exact question. Use ask_user_question only when the task says the user is watching.

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.2.0
+version: 0.4.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:8b594100bee4797b563bd6425dc6f3ff93e1bdfbe9fc5fa1d66b42093c4795e2
-  self_map.md: sha256:d42481b930ef6e59deb1e5c989a9a171e834569b42be9a8d3dda6b2379b0a5ff
-  config_modification_protocol.md: sha256:c67e5fc1611a09203e3ebb1af2c14cacc2878b42a9fb0eb3d190c3b2daddafc3
+  self_map.md: sha256:67eb6223728a72788fa0d75aa56affea2ca48962de2e445293bc12b15f5f70c0
+  config_modification_protocol.md: sha256:f76ee7e2f5a8e699401e3a4c9144643ee64015efd11a266029704bf228be6a95
   memory_guide.md: sha256:6dd1ecfd6a377c4f2cfc2dc299c1ef3835f10d9f313616fd3eb23e5fd3202858
-  delegated.md: sha256:8f7965b6165c3526abb0cd39e44a8b73a8d6a26755049bdcd007baf0b0771087
+  delegated.md: sha256:0a71d5dfa7127df2d51cb5f0e7214240ed88777e36559430a8724c796d7ae561