samagotchi 0.34.0 → 0.36.0

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

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require "digest"
 require "json"
 require "open3"
+require "tmpdir"
 
 # github-pr: a session on a branch with an open GitHub PR gets the PR
 # attached as context (docs/context.md) when its worker starts: a quiet
@@ -10,12 +12,46 @@ require "open3"
 # serves `chi context add <PR URL>` and the web's "+ URL"). Nothing for a
 # scratch session or a delegate child (D12), and nothing, quietly, without
 # gh, its login, a repo or an open PR.
+#
+# Line links: in the web, a `lib/foo.rb:28` (or `lib/foo.rb:28-34`, in
+# inline code too) in the model's answer links to that line of the PR the
+# session reviews: the PR's Files changed view when the lines are in a
+# 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
+# done); before_turn, before_generation and the init task fill the cache
+# off the turn's thread. `bundles: github-pr: line_links: false` turns it
+# off.
 class Plugin
   # gh and git each get this long (a network hang must not keep a thread).
   COMMAND_SECONDS = 20
+  # before_generation looks for a newly attached PR at most this often.
+  GENERATION_CHECK_SECONDS = 30
+
+  def initialize
+    @cache = PrCache.new
+    @generation_checked_at = nil
+  end
 
   def register(chi)
-    chi.init("Looking for this branch's pull request", quiet: true) { |ctx| attach_branch_pr(ctx) }
+    chi.init("Looking for this branch's pull request", quiet: true) do |ctx|
+      summary = attach_branch_pr(ctx)
+      # Inline (an init task has its own thread), whatever the attach
+      # returned (attached already, a child, a scratch session), and after
+      # it, so a PR it just attached is warm for the first answer.
+      refresh(ctx, attached_prs(ctx)) if line_links?(ctx)
+      summary
+    end
+    chi.on(:before_turn) do |event, ctx|
+      # The prompt too: messages is the history before this turn, and a
+      # delegate child's task is its first prompt.
+      kick(ctx, attached_prs(ctx) + PrRef.from_messages(event[:messages], prompt: event[:prompt])) if line_links?(ctx)
+    end
+    chi.on(:before_generation) { |_event, ctx| check_attached(ctx) }
+    # After source-links (90): its links are in the display this one gets.
+    chi.on(:after_turn, priority: 100) { |event, ctx| link_answer(event, ctx) }
   end
 
   # @return [String] what it did (the init task's summary)
@@ -41,11 +77,102 @@ class Plugin
     "no pull request attached"
   end
 
+  # The after_turn handler: links the answer's `path:line` refs from the
+  # PRs' cached data. Never runs gh: nothing cached yet links nothing.
+  def link_answer(event, ctx)
+    return unless line_links?(ctx) && event[:status].to_s == "completed" && event[:present]
+
+    text = LineLinker.last_model_text(event[:messages])
+    return if text.nil? || !text.match?(LineLinker::QUICK)
+
+    prs = (attached_prs(ctx) + PrRef.from_messages(event[:messages])).uniq
+    cached = prs.filter_map { |pr| (data = @cache[pr]) && [pr, data] }
+    return if cached.empty?
+
+    event[:present].call { |display| LineLinker.new(cached).link(display) }
+  end
+
+  # Fetches the PRs in +prs+ whose cache entry is missing or old, on this
+  # thread, unless a refresh runs already (the init task; #kick's thread).
+  def refresh(ctx, prs)
+    stale = @cache.stale(prs.uniq, now)
+    return if stale.empty? || !@cache.claim
+
+    begin
+      stale.each { |pr| fetch(ctx, pr) }
+    ensure
+      @cache.release
+    end
+  end
+
   private
 
+  def line_links?(ctx) = ctx.settings["line_links"] != false
+
+  def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+  # #refresh on its own thread (a raw one, docs/plugins.md), when there is
+  # something to fetch and no refresh runs. Process exit ends it; a gh
+  # still running then finishes alone.
+  def kick(ctx, prs)
+    prs = prs.uniq
+    return if prs.empty? || @cache.refreshing? || @cache.stale(prs, now).empty?
+
+    thread = Thread.new { refresh(ctx, prs) }
+    thread.report_on_exception = false
+  end
+
+  # A PR attached while the turn runs (a parent attaching it right after
+  # `delegate wait: false`), checked at most every GENERATION_CHECK_SECONDS.
+  def check_attached(ctx)
+    return unless line_links?(ctx)
+    return if @generation_checked_at && now - @generation_checked_at < GENERATION_CHECK_SECONDS
+
+    @generation_checked_at = now
+    kick(ctx, attached_prs(ctx))
+  end
+
+  # The session's attached github-pr sources, as PrRefs.
+  def attached_prs(ctx)
+    ctx.context.list.filter_map { |source| PrRef.parse(source[:hint]) if source[:provider] == "github-pr" }
+  rescue StandardError => e
+    ctx.log.debug(:pr_lines_no_sources, error: e.class.name)
+    []
+  end
+
+  # The PR's head and base, and its files when the head moved (or none
+  # are cached). A failure is remembered, so the next kicks wait.
+  def fetch(ctx, pr)
+    shas = run(ctx, "gh", "api", "repos/#{pr.owner}/#{pr.repo}/pulls/#{pr.number}", "--jq",
+               '.head.sha + " " + .base.sha', chdir: Dir.tmpdir).to_s.split
+    return failed(ctx, pr, "no pull request data") unless shas.size == 2
+
+    cached = @cache[pr]
+    files = cached.files if cached && cached.head_sha == shas[0]
+    files ||= fetch_files(ctx, pr) or return failed(ctx, pr, "no file list")
+    @cache.store(pr, PrData.new(head_sha: shas[0], base_sha: shas[1], files: files, fetched_at: now))
+    ctx.log.debug(:pr_lines_fetched, pr: pr.url, files: files.size)
+  rescue StandardError => e
+    failed(ctx, pr, "#{e.class.name}: #{e.message.to_s[0, 200]}")
+  end
+
+  # The PR's files, one JSON object a line (--jq), every page.
+  def fetch_files(ctx, pr)
+    out = run(ctx, "gh", "api", "--paginate", "repos/#{pr.owner}/#{pr.repo}/pulls/#{pr.number}/files?per_page=100",
+              "--jq", ".[] | {filename, status, previous_filename, patch}", chdir: Dir.tmpdir) or return nil
+    out.each_line.filter_map { |line| PrFile.from_api(JSON.parse(line)) unless line.strip.empty? }
+  end
+
+  # Logged once per PR until a fetch of it succeeds (no gh, no login, no
+  # network: every kick would say it again).
+  def failed(ctx, pr, why)
+    ctx.log.info(:pr_lines_not_fetched, pr: pr.url, why: why) if @cache.fail(pr, now)
+    nil
+  end
+
   # stdout of a command that succeeded within COMMAND_SECONDS, else nil.
-  def run(ctx, *command)
-    Open3.popen2(*command, chdir: ctx.cwd, err: File::NULL, pgroup: true) do |stdin, stdout, wait|
+  def run(ctx, *command, chdir: ctx.cwd)
+    Open3.popen2(*command, chdir: chdir, err: File::NULL, pgroup: true) do |stdin, stdout, wait|
       stdin.close
       reader = Thread.new { stdout.read }
       unless wait.join(COMMAND_SECONDS)
@@ -63,3 +190,317 @@ class Plugin
     nil
   end
 end
+
+# A GitHub pull request, by its URL.
+PrRef = Data.define(:owner, :repo, :number)
+
+class PrRef
+  # A PR URL anywhere in a text (trailing text allowed, like the provider's
+  # match: `…/pull/42/files`).
+  URL = %r{https://github\.com/([\w.-]+)/([\w.-]+)/pull/(\d+)}
+  # PRs taken from the user's messages, newest first.
+  FROM_MESSAGES = 3
+
+  # @return [PrRef, nil]
+  def self.parse(text)
+    match = text.to_s.match(URL) or return nil
+    new(owner: match[1], repo: match[2], number: match[3].to_i)
+  end
+
+  # The PRs the user's messages (and +prompt+, the turn's own) name, newest
+  # first, up to FROM_MESSAGES distinct. Not tool results or answers: `gh pr
+  # list` output, logs or a CHANGELOG name unrelated PRs.
+  def self.from_messages(messages, prompt: nil)
+    texts = Array(messages).filter_map do |message|
+      next unless message.is_a?(Hash)
+
+      role = message.key?(:role) ? message[:role] : message["role"]
+      (message.key?(:content) ? message[:content] : message["content"]).to_s if role.to_s == "user"
+    end
+    texts << prompt.to_s if prompt
+    found = []
+    texts.reverse_each do |text|
+      text.scan(URL).reverse_each do |owner, repo, number|
+        pr = new(owner: owner, repo: repo, number: number.to_i)
+        found << pr unless found.include?(pr)
+        return found if found.size >= FROM_MESSAGES
+      end
+    end
+    found
+  end
+
+  def url = "https://github.com/#{owner}/#{repo}/pull/#{number}"
+end
+
+# One file of a PR: its path (the new name), a rename's old one, its status
+# ("added", "modified", "removed", "renamed", …) and its hunks as line
+# ranges on each side (none: a binary file or too large a diff).
+PrFile = Data.define(:path, :previous_path, :status, :new_hunks, :old_hunks)
+
+class PrFile
+  # A hunk header: `@@ -a,b +c,d @@` (a count left out is 1).
+  HUNK = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/
+
+  # @param file [Hash] one entry of the PR files API
+  # @return [PrFile, nil]
+  def self.from_api(file)
+    return nil unless file.is_a?(Hash) && file["filename"].is_a?(String)
+
+    old_hunks = []
+    new_hunks = []
+    file["patch"].to_s.scan(HUNK) do |old_start, old_count, new_start, new_count|
+      old_hunks << span(old_start, old_count)
+      new_hunks << span(new_start, new_count)
+    end
+    new(path: file["filename"], previous_path: file["previous_filename"], status: file["status"].to_s,
+        new_hunks: new_hunks.compact, old_hunks: old_hunks.compact)
+  end
+
+  # A hunk side's lines, or nil for none (`+0,0`: a removed file).
+  def self.span(start, count)
+    count = (count || 1).to_i
+    count.zero? ? nil : start.to_i..(start.to_i + count - 1)
+  end
+
+  def removed? = status == "removed"
+end
+
+# What the cache holds of a PR.
+PrData = Data.define(:head_sha, :base_sha, :files, :fetched_at)
+
+# The PRs' data, per PR, shared by the hooks' threads and the refresh's.
+class PrCache
+  # An entry (or a failed fetch) younger than this isn't fetched again.
+  FRESH_SECONDS = 60
+
+  def initialize
+    @mutex = Mutex.new
+    @entries = {}
+    @failed = {}
+    @refreshing = false
+  end
+
+  # @return [PrData, nil]
+  def [](pr) = @mutex.synchronize { @entries[pr] }
+
+  def store(pr, data)
+    @mutex.synchronize do
+      @entries[pr] = data
+      @failed.delete(pr)
+    end
+  end
+
+  # Remembers a failed fetch; true the first time since the last success.
+  def fail(pr, time)
+    @mutex.synchronize do
+      first = !@failed.key?(pr)
+      @failed[pr] = time
+      first
+    end
+  end
+
+  # The PRs whose entry is missing or older than FRESH_SECONDS (a recent
+  # failure counts as fresh).
+  def stale(prs, time)
+    @mutex.synchronize do
+      prs.reject do |pr|
+        fetched = [@entries[pr]&.fetched_at, @failed[pr]].compact.max
+        fetched && time - fetched < FRESH_SECONDS
+      end
+    end
+  end
+
+  # Takes the one refresh slot: false when a refresh runs.
+  def claim
+    @mutex.synchronize do
+      next false if @refreshing
+
+      @refreshing = true
+    end
+  end
+
+  def release = @mutex.synchronize { @refreshing = false }
+
+  def refreshing? = @mutex.synchronize { @refreshing }
+end
+
+# Links an answer's `path:line` and `path:line-line` refs to the PRs'
+# lines. A ref in inline code links when the code is the ref alone
+# (`` `foo.rb:28` `` becomes ``[`foo.rb:28`](url)``); fenced blocks,
+# markdown links and bare URLs are left alone.
+class LineLinker
+  # The answer is scanned only up to this many characters.
+  MAX_SCAN = 20_000
+  # A path (no spaces), a line, an optional end line and an optional
+  # column (kept in the link's text, not used).
+  REF = %r{(?<![\w./@+~-])(?<path>[\w./@+~-]*[\w@+~-]):(?<from>\d+)(?:-(?<to>\d+))?(?::\d+)?(?![\w/])}
+  REF_ALONE = /\A#{REF}\z/
+  # Whether an answer may hold a ref at all.
+  QUICK = /\S:\d/
+  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,})/
+
+  # The content of the last model message, or nil (string or symbol keys).
+  def self.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"
+
+      return (message.key?(:content) ? message[:content] : message["content"]).to_s
+    end
+    nil
+  end
+
+  # @param prs [Array<Array(PrRef, PrData)>]
+  def initialize(prs)
+    @prs = prs
+  end
+
+  # +text+ with each ref that names exactly one PR's file as a markdown
+  # link; the part beyond MAX_SCAN stays as it is.
+  def link(text)
+    head = text[0, MAX_SCAN]
+    out = +""
+    pos = 0
+    hits(head).each do |start, finish, url|
+      out << head[pos...start] << "[#{head[start...finish]}](#{url})"
+      pos = finish
+    end
+    return text if pos.zero?
+
+    out << head[pos..] << text[MAX_SCAN..].to_s
+  end
+
+  # 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)
+    found = @prs.filter_map do |pr, data|
+      file = resolve(data.files, path)
+      [pr, data, file] if file
+    end
+    return nil unless found.size == 1
+
+    line_url(*found.first, from, to)
+  end
+
+  private
+
+  # [start, finish, url] for each ref to link, by offset.
+  def hits(text)
+    fences = fenced_blocks(text)
+    skipped = fences + spans(text, URL_SPAN) + spans(text, MARKDOWN_LINK)
+    code = inline_code(text, fences)
+    found = []
+    code.each do |start, finish, inner|
+      next if inside_any?(skipped, start, finish)
+
+      match = inner.strip.match(REF_ALONE) or next
+      url = ref_url(match) and found << [start, finish, url]
+    end
+    text.scan(REF) do
+      match = Regexp.last_match
+      start = match.begin(0)
+      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]
+    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)
+    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)
+  end
+
+  # The PR file +path+ names: the path (or a rename's old one) exactly,
+  # after a leading `./`; else the longest PR path +path+ ends with on a
+  # `/` boundary (an absolute path into a worktree); else the one PR path
+  # that ends with +path+ (a bare `foo.rb`). nil: none, or several.
+  def resolve(files, path)
+    path = path.sub(%r{\A(?:\./)+}, "")
+    exact = files.find { |file| file.path == path } || files.find { |file| file.previous_path == path }
+    return exact if exact
+
+    longer = files.select { |file| path.end_with?("/#{file.path}") }.max_by { |file| file.path.length }
+    return longer if longer
+
+    shorter = files.select { |file| file.path.end_with?("/#{path}") }
+    shorter.one? ? shorter.first : nil
+  end
+
+  # 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.
+  def line_url(pr, data, file, from, to)
+    last = to || from
+    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}"
+    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}"
+  end
+
+  # [start, finish, inner] for each inline code span outside +fences+: a
+  # run of backticks to the next run of the same length.
+  def inline_code(text, fences)
+    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 }
+    found = []
+    index = 0
+    while index < runs.size
+      start, finish = runs[index]
+      closing = by_length[finish - start].bsearch { |other| other > index }
+      if closing
+        found << [start, runs[closing][1], text[finish...runs[closing][0]]]
+        index = closing + 1
+      else
+        index += 1
+      end
+    end
+    found
+  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
+
+  def spans(text, regex)
+    found = []
+    text.scan(regex) { found << [Regexp.last_match.begin(0), Regexp.last_match.end(0)] }
+    found
+  end
+
+  def inside_any?(spans, start, finish)
+    spans.any? { |span_start, span_end| start >= span_start && finish <= span_end }
+  end
+end

data/lib/samagotchi/bundles/guardrails/guardrails/rules.yml

@@ -60,6 +60,17 @@ rules:
     verdict: ask
     reason: rm -rf on a path outside the working tree
 
+  # memory_write remove: true moves a memory into the bundle trash. Memory
+  # files don't count as outside the repo, so nothing else asks; a delegate
+  # child could otherwise take its parent's handoff away. Every removal
+  # asks, once at a time.
+  - id: memory-remove
+    tool: memory_write
+    memory: remove
+    verdict: ask
+    scopes: [once]
+    reason: removes a memory (it goes to the bundle trash, which chi bundle trash lists)
+
   # ── running code from the network ──────────────────────────────────────
   - id: pipe-to-shell
     tool: shell
@@ -128,6 +139,17 @@ rules:
     scopes: [once]
     reason: attaches a command chi will run every few minutes, outside the guardrails
 
+  # ── chi broadcast: for the user, not an agent ─────────────────────────
+  # chi broadcast refuses to run inside a session (SAMAGOTCHI_PARENT_SESSION
+  # is set there), but an agent can unset that; this asks every time, and
+  # only the user may allow it. Quoted words and continuations still match.
+  - id: chi-broadcast
+    tool: shell
+    command: '\bchi["'']?[\s\\]+["'']?broadcast\b'
+    verdict: ask
+    scopes: [once]
+    reason: shares a note with every session it may concern; chi broadcast is for the user, not an agent
+
   # ── answering chi's own questions around chi answer ───────────────────
   # A parent agent answers a child's approval with chi answer, which holds it
   # to guardrails.parent_approvals. These shapes go around that: chi --attach

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

@@ -1,11 +1,12 @@
 ---
 name: guardrails
-version: 0.6.0
+version: 0.8.0
 scope: system
-description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, git hooks, chi's own config and attached context from the shell, chi context add --cmd, answering chi around chi answer; in strict mode also git rebase and writes and git in another checkout outside the session's repo), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
+description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, git hooks, chi's own config and attached context from the shell, chi context add --cmd, chi broadcast, answering chi around chi answer, removing a memory; in strict mode also git rebase and writes and git in another checkout outside the session's repo), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
 trust_level: reviewed
 # models: in small-models.yml (guardrails.small_models) needs 0.8.1; git: in rules.yml needs 0.17.0;
-# skip_read_only:, touches:, rm: and modes: need 0.20.0
-requires_chi: ">= 0.20.0"
+# a rule's memory: key (memory-remove) needs 0.36.0: an older chi refuses the rule set (unknown key), so every
+# guarded call would be refused
+requires_chi: ">= 0.36.0"
 files:
   guardrails.md: sha256:04207fd1738aeeeef3b7a8053fc57597565bddd7862f01acaba784419cbd909b

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

@@ -1,11 +1,11 @@
 ---
 name: mcp
-version: 0.4.5
+version: 0.5.0
 scope: system
 description: "Tools from MCP servers (stdio): each server in config.yml bundles: mcp: servers: runs for the session, its tools are mcp_<server>_<tool>; /mcp lists them"
 trust_level: reviewed
 files: {}
 plugin:
   file: plugin.rb
-  sha256: sha256:1ebedc86cd21c918766c794015b6bd16c397c0f7e2734d939d8310d446b8a9a1
+  sha256: sha256:b946862b2c74734dd5af9ffba12f14a79b760b993a1248630f9fc5ecaaa740f5
 requires_chi: ">= 0.33.0"

data/lib/samagotchi/bundles/mcp/plugin.rb

@@ -27,11 +27,14 @@
 # A server that doesn't start, answer or list its tools is skipped with a
 # notice; the rest of chi works. One that exits mid-session starts again on
 # its next call, at most MAX_RESTARTS times a session. /mcp lists the
-# servers and their tools.
+# servers and their tools, with an estimate of the tokens their
+# definitions take in every request.
 require "digest"
 require "json"
 require "open3"
 require "samagotchi/process_group"
+require "samagotchi/token_usage"
+require "samagotchi/tool_declarations"
 require "time"
 require "shellwords"
 require "tmpdir"
@@ -47,6 +50,8 @@ class Plugin
   CACHE_TTL = 24 * 60 * 60
   # Restarts of a server that exited, per session.
   MAX_RESTARTS = 3
+  # The states whose server's tools the model has (what publish declares).
+  OFFERED = %i[running cached exited].freeze
   IMAGE_EXT = { "image/png" => "png", "image/jpeg" => "jpg", "image/gif" => "gif", "image/webp" => "webp" }.freeze
 
   # A JSON-RPC client for one MCP server over stdio: newline-delimited JSON
@@ -244,11 +249,12 @@ class Plugin
 
   # One configured server: its service, state and tools. +listed+ is its
   # tools/list as the server answers it (what the cache keeps), +tools+
-  # the ones chi offers (the tools: filter applied, each with chi_name).
+  # the ones chi offers (the tools: filter applied, each with chi_name),
+  # +tokens+ their definitions' estimated size (#definition_tokens).
   # +client+ is the running process's (a restart replaces it; the
   # service's stop closes the current one), +restarts+ how many it had.
   Server = Struct.new(:name, :config, :service, :state, :error, :tools, :listed, :timeout, :cwd, :command, :env,
-                      :digest, :cached_at, :relist, :relisting, :client, :restarts, keyword_init: true)
+                      :digest, :cached_at, :relist, :relisting, :client, :restarts, :tokens, keyword_init: true)
 
   def initialize(settings = {})
     @settings = settings
@@ -278,7 +284,7 @@ class Plugin
     configs = {} unless configs.is_a?(Hash)
     @servers = configs.map do |name, config|
       server = Server.new(name: name.to_s, config: config.is_a?(Hash) ? config : {}, state: :starting, tools: [],
-                          restarts: 0)
+                          restarts: 0, tokens: 0)
       server.timeout = positive(server.config["timeout"]) || @timeout
       resolve(server, ctx)
       server.service = chi.service(name) { |svc| start(server, svc, ctx) }
@@ -506,24 +512,43 @@ class Plugin
   # ── Tools ─────────────────────────────────────────────────────────────
 
   # Declare the server's tools on +target+ (chi at load, or the set of
-  # chi.replace_tools later), the tools: filter applied.
+  # chi.replace_tools later), the tools: filter applied. Their estimated
+  # tokens go to the log when they changed.
   def declare(target, server, ctx)
     wanted = server.config["tools"] && Array(server.config["tools"]).map(&:to_s)
     tools = server.listed.map(&:dup)
     tools = tools.select { |tool| wanted.any? { |w| File.fnmatch(w, tool["name"], File::FNM_EXTGLOB) } } if wanted
     server.tools = tools
+    tokens = 0
     tools.each do |tool|
       name = tool_name(server.name, tool["name"])
-      target.tool(name, description(tool), schema: tool["inputSchema"] || { "type" => "object", "properties" => {} },
+      schema = tool["inputSchema"] || { "type" => "object", "properties" => {} }
+      target.tool(name, description(tool), schema: schema,
                                            label: "#{server.name}: #{tool["name"]}", preview: ->(args) { preview(args) }) do |args, call_ctx|
         call(server, tool["name"], args, call_ctx)
       end
       tool["chi_name"] = name
+      tokens += definition_tokens(name, description(tool), schema)
     rescue ArgumentError => e
       text = "MCP tool #{server.name}/#{tool["name"]} left out: #{e.message}"
       ctx.notify(text, level: :warn) unless @left_out.include?(text)
       @left_out << text
     end
+    return if tokens == server.tokens
+
+    server.tokens = tokens
+    ctx.log.info("mcp_tools_estimated", server: server.name, tools: tools.count { |tool| tool["chi_name"] },
+                                        tokens: tokens)
+  end
+
+  # A tool's definition as the chat path sends it (LLM::ChatLoop#tool_definitions:
+  # the chat schema, wrapped as a function), in estimated tokens
+  # (TokenUsage::CHARS_PER_TOKEN). The native prompts (Gemma, Qwen) render a
+  # flatter schema, so it is an upper bound there.
+  def definition_tokens(name, description, schema)
+    spec = Samagotchi::Plugin::Api.tool_spec(name, description, schema: schema) { nil }
+    function = Samagotchi::ToolDeclarations.chat_schemas([spec[:schema]]).first.slice(:name, :description, :parameters)
+    Samagotchi::TokenUsage.estimate(JSON.generate({ type: "function", function: function }))
   end
 
   # The servers' tools changed after load (a live list that differs from
@@ -532,7 +557,7 @@ class Plugin
   def publish(ctx)
     @publish.synchronize do
       @chi.replace_tools do |set|
-        @servers.each { |server| declare(set, server, ctx) if %i[running cached exited].include?(server.state) }
+        @servers.each { |server| declare(set, server, ctx) if OFFERED.include?(server.state) }
       end
     end
   end
@@ -750,20 +775,24 @@ class Plugin
   def listing
     return "No servers. Add them in config.yml under `bundles: mcp: servers:` (docs/plugins.md, The mcp bundle)." if @servers.empty?
 
-    @servers.map do |server|
+    servers = @servers.map do |server|
       head = "**#{server.name}**: #{state_text(server)}"
       # Sorted: a server lists its tools in its own (often grouped) order.
       tools = server.tools.map { |tool| tool["chi_name"] }.compact.sort
       tools.empty? ? head : "#{head}\n#{tools.map { |t| "- `#{t}`" }.join("\n")}"
-    end.join("\n\n")
+    end
+    total = @servers.sum { |server| OFFERED.include?(server.state) ? server.tokens : 0 }
+    [*servers, "Total: ~#{thousands(total)} tokens of tool definitions in every request " \
+               "(estimated: their JSON as the chat API gets it, ÷ #{format("%g", Samagotchi::TokenUsage::CHARS_PER_TOKEN)})."]
+      .join("\n\n")
   end
 
   def state_text(server)
     case server.state
-    when :cached then "cached (not started), #{server.tools.size} tool#{"s" unless server.tools.size == 1}"
+    when :cached then "cached (not started), #{server.tools.size} tool#{"s" unless server.tools.size == 1}, #{tokens_text(server)}"
     when :running
       count = server.tools.count { |tool| tool["chi_name"] }
-      "running (pid #{server.client.pid}), #{count} tool#{"s" unless count == 1}"
+      "running (pid #{server.client.pid}), #{count} tool#{"s" unless count == 1}, #{tokens_text(server)}"
     when :starting then "starting"
     else "#{server.state == :failed ? "failed" : "stopped"}: #{server.error}"
     end
@@ -771,6 +800,10 @@ class Plugin
     "stopped"
   end
 
+  def tokens_text(server) = "~#{thousands(server.tokens)} tokens"
+
+  def thousands(number) = number.to_s.reverse.scan(/\d{1,3}/).join(",").reverse
+
   def positive(value)
     number = Float(value.to_s, exception: false)
     number&.positive? ? number : nil