samagotchi 0.42.0 → 0.44.0

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

@@ -3,6 +3,7 @@
 require "digest"
 require "json"
 require "open3"
+require "time"
 require "tmpdir"
 
 # github-pr: a session on a branch with an open GitHub PR gets the PR
@@ -24,15 +25,31 @@ require "tmpdir"
 # 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.
+#
+# `bundles: github-pr: auto_attach:` says what the init task does with the
+# branch's open PR: `attach` (the default), `offer` (a card with Attach and
+# Not here, which run /pr-attach N and /pr-decline N; nothing attached until
+# a click; offered once per session) or `off` (nothing). In offer mode the
+# offers, their outcomes and each session's first prompt go to
+# <data_dir>/offers.ndjson (OffersLog), to find heuristics later.
 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
+  # auto_attach's values (YAML's bare true/false: attach/off).
+  AUTO_ATTACH_MODES = { "attach" => :attach, "offer" => :offer, "off" => :off, true => :attach, false => :off }.freeze
+  # /pr-attach and /pr-decline take a PR number (`42` or `#42`).
+  PR_NUMBER = /\A#?(\d+)\z/
+  # The offer card's line under the PR's title.
+  OFFER_LINE = "Not attached: the agent gets nothing until you attach it."
+  # first_prompt keeps this much of the prompt.
+  FIRST_PROMPT_CHARS = 160
 
   def initialize
     @cache = PrCache.new
     @generation_checked_at = nil
+    @warned_mode = false
   end
 
   def register(chi)
@@ -48,6 +65,13 @@ class Plugin
       # 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)
+      log_first_prompt(event, ctx)
+    end
+    chi.command("/pr-attach", "Attach the PR this session was offered: /pr-attach 42", anytime: true) do |args, ctx|
+      offer_command("/pr-attach", args, ctx) { |number, offer| attach_offered(ctx, number, offer) }
+    end
+    chi.command("/pr-decline", "Don't attach the PR this session was offered: /pr-decline 42", anytime: true) do |args, ctx|
+      offer_command("/pr-decline", args, ctx) { |number, offer| decline_offered(ctx, number, offer) }
     end
     chi.on(:before_generation) { |_event, ctx| check_attached(ctx) }
     # After source-links (90): its links are in the display this one gets.
@@ -60,15 +84,19 @@ class Plugin
     return "skipped: a delegate child" if ctx.delegate?
     return "no session yet" unless ctx.session_id
 
+    mode = auto_attach_mode(ctx)
+    return "auto_attach: off" if mode == :off
+
     branch = run(ctx, "git", "branch", "--show-current").to_s.strip
     return "not on a branch" if branch.empty?
 
-    json = run(ctx, "gh", "pr", "view", "--json", "number,url,state") or return "no pull request for #{branch}"
+    json = run(ctx, "gh", "pr", "view", "--json", "number,url,state,title") or return "no pull request for #{branch}"
     pr = JSON.parse(json)
     return "pull request ##{pr["number"]} isn't open" unless pr["state"] == "OPEN"
 
     name = "pr-#{pr["number"]}"
     return "#{name} is attached already" if ctx.context.list.any? { |source| source[:name] == name || source[:hint] == pr["url"] }
+    return offer_branch_pr(ctx, branch, pr, name) if mode == :offer
 
     attached = ctx.context.attach(url: pr["url"], name: name, why: "branch #{branch} has open PR ##{pr["number"]}")
     attached ? "attached #{name}" : "#{name} was removed from this session; not attached again"
@@ -77,6 +105,21 @@ class Plugin
     "no pull request attached"
   end
 
+  # `bundles: github-pr: auto_attach:`, read at each worker start.
+  # @return [Symbol] :attach, :offer or :off; an unknown value is :attach
+  #   (logged once)
+  def auto_attach_mode(ctx)
+    value = ctx.settings["auto_attach"]
+    return :attach if value.nil?
+
+    key = value.is_a?(String) ? value.strip.downcase : value
+    AUTO_ATTACH_MODES.fetch(key) do
+      ctx.log.warn(:pr_auto_attach_unknown, value: value.to_s[0, 40]) unless @warned_mode
+      @warned_mode = true
+      :attach
+    end
+  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)
@@ -109,6 +152,106 @@ class Plugin
 
   def line_links?(ctx) = ctx.settings["line_links"] != false
 
+  def offer_card_id(number) = "github-pr-offer-#{number}"
+
+  # Offer mode: a card instead of the attach, once per session per PR (a
+  # worker restart finds the offered marker). The marker is written after
+  # the card, so a card that failed leaves none.
+  def offer_branch_pr(ctx, branch, pr, name)
+    return "#{name} was removed from this session; not offered" if ctx.context.declined?(name, url: pr["url"])
+    return "#{name} was offered already" if ctx.context.offered(name)
+
+    number = pr["number"]
+    body = [pr["title"].to_s.gsub(/\s+/, " ").strip, OFFER_LINE].reject(&:empty?).join("\n\n")
+    ctx.card(id: offer_card_id(number), title: "PR ##{number} for branch #{branch}", body: body, level: :info,
+             actions: [{ label: "Attach", command: "/pr-attach #{number}" },
+                       { label: "Not here", command: "/pr-decline #{number}" }])
+    ctx.context.mark_offered(name, pr["url"], why: "branch #{branch} has open PR ##{number}")
+    offers_log(ctx).write("offered", session: ctx.session_id, project_root: project_root(ctx), cwd: ctx.cwd,
+                                     branch: branch, pr: pr["url"], checkout: checkout_kind(ctx), model: ctx.model)
+    "offered #{name}"
+  end
+
+  # /pr-attach and /pr-decline: the PR number and its offer, else the
+  # answer (a usage line, no offer).
+  def offer_command(command, args, ctx)
+    number = args.to_s.strip[PR_NUMBER, 1] or return "usage: #{command} <PR number>, as the offer card names it"
+    number = number.to_i
+    offer = ctx.context.offered("pr-#{number}")
+    return "no offered PR ##{number} here; use `chi context add <PR URL>`" unless offer
+
+    yield number, offer
+  rescue Samagotchi::Plugin::AttachedContext::Error => e
+    "pr-#{number} not changed: #{e.message}"
+  end
+
+  # The user's click: attached as auto-attach would, past a decline, with
+  # the offer's why (no git or gh here).
+  def attach_offered(ctx, number, offer)
+    why = "#{offer.why || "open PR ##{number}"} (attached from the offer)"
+    attached = ctx.context.attach(url: offer.hint, name: offer.name, why: why, force: true)
+    return "#{offer.name} wasn't attached" unless attached
+
+    ctx.card(id: offer_card_id(number), title: "PR ##{number}", body: "Attached #{attached}")
+    offers_log(ctx).write("attached", session: ctx.session_id, pr: offer.hint, seconds: seconds_since(offer))
+    nil
+  end
+
+  # Not for a PR attached here already (a stale card): that is
+  # `chi context rm`'s, and a declined marker would leave it attached.
+  def decline_offered(ctx, number, offer)
+    attached = ctx.context.list.find { |source| source[:name] == offer.name || source[:hint] == offer.hint }
+    return "#{attached[:name]} is attached here; `chi context rm #{attached[:name]}` removes it" if attached
+
+    ctx.context.decline(url: offer.hint, name: offer.name)
+    ctx.card(id: offer_card_id(number), title: "PR ##{number}", body: "Not attached here; + URL attaches it")
+    offers_log(ctx).write("declined", session: ctx.session_id, pr: offer.hint, seconds: seconds_since(offer))
+    nil
+  end
+
+  def seconds_since(offer)
+    (Time.now - Time.iso8601(offer.at.to_s)).round
+  rescue ArgumentError
+    nil
+  end
+
+  # Offer mode: every session's first prompt (offered or not; a web chat's
+  # first turn starts before the init task's gh returns), joined to the
+  # offers by session at analysis time. First = no user message yet (a
+  # context note may be in messages already).
+  def log_first_prompt(event, ctx)
+    return if event[:prompt].nil? || auto_attach_mode(ctx) != :offer
+    return if Array(event[:messages]).any? { |message| message_role(message) == "user" }
+    return if ctx.scratch? || ctx.delegate? || ctx.session_id.nil?
+
+    offers_log(ctx).write("first_prompt", session: ctx.session_id, prompt: event[:prompt].to_s[0, FIRST_PROMPT_CHARS])
+  rescue StandardError => e
+    ctx.log.debug(:pr_offers_log_failed, error: e.class.name)
+  end
+
+  def message_role(message)
+    return nil unless message.is_a?(Hash)
+
+    (message.key?(:role) ? message[:role] : message["role"]).to_s
+  end
+
+  def offers_log(ctx) = OffersLog.new(File.join(ctx.data_dir, OffersLog::FILE), ctx.log)
+
+  def project_root(ctx)
+    ctx.repo_root
+  rescue StandardError
+    nil
+  end
+
+  # "main" for the main checkout, "worktree" for a linked one (its git dir
+  # isn't the common one), nil outside a repo.
+  def checkout_kind(ctx)
+    dirs = run(ctx, "git", "rev-parse", "--path-format=absolute", "--git-dir", "--git-common-dir").to_s.split("\n")
+    return nil unless dirs.size == 2
+
+    dirs[0] == dirs[1] ? "main" : "worktree"
+  end
+
   def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
   # #refresh on its own thread (a raw one, docs/plugins.md), when there is
@@ -191,6 +334,39 @@ class Plugin
   end
 end
 
+# <data_dir>/offers.ndjson: one JSON object a line, {event:, ts:, …},
+# private to the user (0600: it holds prompts). Every worker shares it, so
+# each write holds offers.ndjson.lock (flock) around the size check, the
+# rotation and the append; over MAX_BYTES the file becomes
+# offers.ndjson.1 (one old file kept). A failure is logged at debug: the
+# log never breaks an attach.
+class OffersLog
+  FILE = "offers.ndjson"
+  MAX_BYTES = 1024 * 1024
+  LINE_MAX_BYTES = 4000
+  MODE = 0o600
+
+  def initialize(path, log)
+    @path = path
+    @log = log
+  end
+
+  def write(event, **fields)
+    line = "#{JSON.generate({ event: event, ts: Time.now.utc.iso8601 }.merge(fields))}\n"
+    return @log.debug(:pr_offers_line_too_long, event: event) if line.bytesize > LINE_MAX_BYTES
+
+    File.open("#{@path}.lock", File::RDWR | File::CREAT, MODE) do |lock|
+      lock.flock(File::LOCK_EX)
+      File.rename(@path, "#{@path}.1") if File.size?(@path).to_i > MAX_BYTES
+      File.open(@path, File::WRONLY | File::APPEND | File::CREAT, MODE) { |file| file.write(line) }
+    end
+    nil
+  rescue StandardError => e
+    @log.debug(:pr_offers_log_failed, error: e.class.name)
+    nil
+  end
+end
+
 # A GitHub pull request, by its URL.
 PrRef = Data.define(:owner, :repo, :number)
 

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

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

data/lib/samagotchi/context_sources.rb

@@ -22,6 +22,7 @@ module Samagotchi
   #   sessions/<id>/subscriptions.json             {name => Subscription}; the worker writes it
   #   sessions/<id>/muted/<name>                   a marker: this session ignores <name>
   #   sessions/<id>/declined/<name>                a marker (its hint inside): the user removed <name>
+  #   sessions/<id>/offered/<name>                 a marker ({hint, why, at}): a plugin offered <name> (ctx.context.mark_offered)
   # The guardrails protect the root (ProtectedPaths, CHI_TEXT): a source's
   # command runs later, outside the gate.
   module ContextSources
@@ -39,6 +40,7 @@ module Samagotchi
     SUBSCRIPTIONS_FILE = "subscriptions.json"
     MUTED_DIR = "muted"
     DECLINED_DIR = "declined"
+    OFFERED_DIR = "offered"
 
     # A name, a command, a value the store can't take.
     class Invalid < ArgumentError; end
@@ -131,6 +133,11 @@ module Samagotchi
     # What a command printed or a push sent (the contract, ContextSources.parse_output).
     Fetched = Data.define(:text, :summary, :wake, :hint)
 
+    # A plugin's offer of a source to a session (ctx.context.mark_offered):
+    # +hint+ (often the URL), +why+ (the plugin's reason, for the attach
+    # that may follow; nil for none) and +at+, when it was offered (ISO 8601).
+    Offer = Data.define(:name, :hint, :why, :at)
+
     # A source as one session sees it: the definition, where it lives, and
     # +shadowed+ for a project source hidden by a session one of its name.
     Attached = Data.define(:source, :location, :shadowed) do
@@ -273,6 +280,39 @@ module Samagotchi
         AtomicFile.write(declined_path(name), "#{hint}\n")
       end
 
+      # Clears the declined marker of +name+ and any whose hint is +hint+
+      # (the user's explicit attach: a URL declined under another name).
+      def undecline(name, hint: nil)
+        FileUtils.rm_f(declined_path(name))
+        folder = File.join(dir, DECLINED_DIR)
+        return if hint.to_s.empty? || !Dir.exist?(folder)
+
+        Dir.children(folder).each do |file|
+          path = File.join(folder, file)
+          FileUtils.rm_f(path) if File.read(path).strip == hint
+        rescue SystemCallError
+          nil
+        end
+      end
+
+      def offered_path(name) = File.join(dir, OFFERED_DIR, ContextSources.check_name!(name))
+
+      # Session only: a plugin offered +name+ here (so it doesn't offer it
+      # again). Neither an add nor a decline clears it.
+      # @return [Offer]
+      def mark_offered(name, hint, why: nil, at: Time.now)
+        offer = Offer.new(name: ContextSources.check_name!(name), hint: hint, why: why, at: at.utc.iso8601)
+        FileUtils.mkdir_p(File.join(dir, OFFERED_DIR))
+        AtomicFile.write(offered_path(name), "#{JSON.generate({ "hint" => offer.hint, "why" => offer.why, "at" => offer.at }.compact)}\n")
+        offer
+      end
+
+      # @return [Offer, nil]
+      def offered(name)
+        data = ContextSources.read_json(offered_path(name))
+        data.is_a?(Hash) ? Offer.new(name: name, hint: data["hint"], why: data["why"], at: data["at"]) : nil
+      end
+
       # Session only: the markers and the worker's subscription file.
       def muted?(name) = File.exist?(File.join(dir, MUTED_DIR, ContextSources.check_name!(name)))
 

data/lib/samagotchi/context_status.rb

@@ -63,13 +63,21 @@ module Samagotchi
       "context elevated — be concise, prefer range reads, avoid re-reading large files",
       "context critical — summarize aggressively, avoid large outputs, delegate broad work to subagents"
     ].freeze
+    # The top level's words when the buckets count against a budget
+    # (llm_context.budget_tokens) and no forget layer: nothing in the
+    # model's hands shrinks the context, so no "summarize".
+    BUDGET_CRITICAL = "context budget critical — avoid large outputs and re-reads, delegate broad work to subagents"
 
     # @param bucket [String] "under<N>" or "<N>plus"
     # @param thresholds [Array<Integer>] the configured ones, sorted
-    def self.guidance(bucket, thresholds = DEFAULT_THRESHOLDS)
+    # @param budget [Boolean] the buckets count against a budget
+    def self.guidance(bucket, thresholds = DEFAULT_THRESHOLDS, budget: false)
       rank = bucket_rank(bucket, thresholds)
       level = rank < GUIDANCE_FROM_RANK ? 0 : GUIDANCE.size - 1 - (thresholds.size - rank)
-      GUIDANCE[level.clamp(0, GUIDANCE.size - 1)]
+      level = level.clamp(0, GUIDANCE.size - 1)
+      return BUDGET_CRITICAL if budget && level == GUIDANCE.size - 1
+
+      GUIDANCE[level]
     end
 
     # 0 for the bucket under the first threshold, then one per threshold.
@@ -331,11 +339,16 @@ module Samagotchi
 
     def k(tokens) = tokens >= 1000 ? "#{(tokens / 1000.0).round}k" : tokens.to_s
 
+    # The buckets count against the budget (set, and not over the window).
+    def budget_counted?(usage) = !@budget.nil? && usage[:window_tokens] == @budget
+
     def guidance_message(usage:, bucket:)
       how = usage[:source].to_s == "server" ? "as the server reports" : "estimated"
+      budget = budget_counted?(usage)
+      of = budget ? "the context budget (#{k(@budget)} tokens)" : "the context window"
       { role: "system", kind: LINE_KIND,
-        content: "#{LINE_PREFIX}about #{usage[:estimated_pct].to_f.round}% of the context window is in use " \
-                 "(#{how}; bucket=#{bucket}). #{self.class.guidance(bucket, @thresholds)}]" }
+        content: "#{LINE_PREFIX}about #{usage[:estimated_pct].to_f.round}% of #{of} is in use " \
+                 "(#{how}; bucket=#{bucket}). #{self.class.guidance(bucket, @thresholds, budget: budget)}]" }
     end
 
     def status_message(usage:, bucket:)
@@ -350,7 +363,7 @@ module Samagotchi
         bucket: bucket,
         thresholds: @thresholds.join(","),
         src: usage[:source],
-        guidance: self.class.guidance(bucket, @thresholds)
+        guidance: self.class.guidance(bucket, @thresholds, budget: budget_counted?(usage))
       )
     end
   end

data/lib/samagotchi/kernel_loop.rb

@@ -28,6 +28,7 @@ require_relative "tool_ids"
 require_relative "llm_context_view"
 require_relative "llm_context_apply"
 require_relative "llm_context_forget"
+require_relative "llm_context_notice"
 require_relative "answer_display"
 require_relative "llm/model_result"
 require_relative "llm/turn_settings"
@@ -279,7 +280,8 @@ module Samagotchi
     def start_turn(messages, on_stream_event:, cancel_controller:, pending_input:, cap:)
       conversation = prepare_conversation(messages)
       context = ContextStatus.new(conversation: conversation, llm_context: @turn_settings.llm_context)
-      @llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: context)
+      emit = ->(event) { emit_stream_event(on_stream_event, event) }
+      @llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: context, emit: emit)
       Turn.new(
         conversation: conversation, context: context,
         empty_retry: EmptyAnswerRetry.new, empty_steps: [], tool_activity: [], buffer: +"", streamed_thinking: +"",
@@ -290,7 +292,7 @@ module Samagotchi
         prefill: Thinking.native(@turn_settings.thinking || Thinking::DEFAULT, @profile).prefill,
         pending_tool_calls: false, model_name: @turn_settings.model_name, pending_input: pending_input,
         on_stream_event: on_stream_event, cancel_controller: cancel_controller, cap: cap,
-        emit: ->(event) { emit_stream_event(on_stream_event, event) }
+        emit: emit
       )
     end
 
@@ -321,7 +323,7 @@ module Samagotchi
     # (the prompt cache keeps its prefix), and the prompt is formatted again
     # with it.
     def prepare_request(turn)
-      apply_llm_context!(turn.conversation, context: turn.context)
+      apply_llm_context!(turn.conversation, context: turn.context, emit: turn.emit)
       prompt, images = format_prompt(turn)
       image_tokens = images.empty? ? 0 : ImagePlan.estimated_tokens(turn.conversation)
       window = ContextWindow.resolve(client: @client, model: turn.model_name, setting: @turn_settings.window_setting)
@@ -580,7 +582,7 @@ module Samagotchi
       # The model answered: the staged edits reach the session now (a turn
       # that ran out of steps, on tool results or on a retry's nudge, is
       # mid-task; they wait).
-      apply_llm_context!(turn.conversation, moment: :turn_end) if turn.answered
+      apply_llm_context!(turn.conversation, moment: :turn_end, emit: turn.emit) if turn.answered
       # An empty answer left the conversation: an earlier model message
       # isn't this turn's answer.
       output = turn.ended_empty ? "" : strip_thought_blocks(last_model_content(turn.conversation))
@@ -784,8 +786,8 @@ module Samagotchi
         return "Error: forget_outputs is off (the llm_context strategy has no forget layer)"
       end
 
-      LLMContextForget.call(turn, call, llm_context: llm_context,
-                                        apply: -> { apply_llm_context!(turn.conversation, llm_context, context: turn.context) })
+      apply = -> { apply_llm_context!(turn.conversation, llm_context, context: turn.context, emit: turn.emit) }
+      LLMContextForget.call(turn, call, llm_context: llm_context, apply: apply)
     end
 
     # Before each request of both loops (+moment+ :request; the warm-up
@@ -797,10 +799,12 @@ module Samagotchi
     # first, and the warm-up) is the first with the stubs. +context+: the
     # turn's ContextStatus (payoff applies in its top bucket; an applied
     # batch rebases its estimate, ContextStatus#edited!). none changes
-    # nothing. Logged as llm_context_apply when a batch is applied.
+    # nothing. Logged as llm_context_apply when a batch is applied, and
+    # shown to the user as a ✂ row (+emit+ takes the :llm_context_edited
+    # event, LLMContextNotice; the warm-up's own copy has none).
     # @return [LLMContextApply::Outcome]
     def apply_llm_context!(conversation, llm_context = @turn_settings&.llm_context, moment: :request, context: nil,
-                           warmup: false)
+                           warmup: false, emit: nil)
       view = llm_context_view(llm_context)
       return LLMContextApply::Outcome.none if view.none?
 
@@ -811,7 +815,10 @@ module Samagotchi
       if outcome.applied?
         # The prompt just shrank: the context estimate counts from it.
         context&.edited!
-        log_llm_context(outcome, llm_context, moment) unless warmup
+        unless warmup
+          log_llm_context(outcome, llm_context, moment)
+          emit_llm_context(emit, conversation, outcome, moment) if emit
+        end
       end
       outcome
     end
@@ -825,6 +832,14 @@ module Samagotchi
     end
     private :log_llm_context
 
+    # The batch's ✂ row; a row that can't be built never breaks the turn.
+    def emit_llm_context(emit, conversation, outcome, moment)
+      emit.call(LLMContextNotice.event(conversation, outcome, moment: moment))
+    rescue StandardError => e
+      Log.warn(:model, "llm_context_notice_failed", error: e.class.name, message: e.message)
+    end
+    private :emit_llm_context
+
     # A request's re-prefilled tokens, for both loops: of the prompt the
     # last request on +model+ sent (this kernel's, any turn), what the
     # server didn't reuse from its cache this time (that prompt less

data/lib/samagotchi/llm/chat_loop.rb

@@ -358,7 +358,8 @@ module Samagotchi
           # steps from them (ModelResult#empty_steps).
           @empty_steps = []
           @context = ContextStatus.new(conversation: conversation, llm_context: loop.llm_context)
-          loop.llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: @context)
+          loop.llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: @context,
+                                                             emit: method(:emit))
         end
 
         def call(max_iterations:, cap:)
@@ -455,7 +456,7 @@ module Samagotchi
         def generate(iteration)
           # The strategy's edits the apply rule lets through first (stale):
           # this request sends them.
-          @loop.apply_llm_context!(@conversation, context: @context)
+          @loop.apply_llm_context!(@conversation, context: @context, emit: method(:emit))
           window = @window = @loop.context_window(@model_name)
           observe_context(iteration, window)
           retry_generation = @empty_retry.take_sampling!
@@ -640,7 +641,7 @@ module Samagotchi
         def result(text, exhausted:)
           # The model answered: the staged edits reach the session now (a
           # turn that ran out of steps is mid-task; they wait).
-          @loop.apply_llm_context!(@conversation, moment: :turn_end) unless exhausted
+          @loop.apply_llm_context!(@conversation, moment: :turn_end, emit: method(:emit)) unless exhausted
           ModelResult.new(text: text, conversation: @loop.plain(@conversation), exhausted: exhausted,
                           tool_activity: @tool_activity, empty_steps: @empty_steps, empty_retries: @empty_retry.attempts,
                           context_status: @context.display)

data/lib/samagotchi/llm_context_forget.rb

@@ -44,8 +44,12 @@ module Samagotchi
     SMALL = 80
 
     # The turn a forget_outputs call runs in: its conversation (the
-    # entries the edits are saved on) and its ContextStatus (nil: none).
-    Turn = Data.define(:conversation, :context)
+    # entries the edits are saved on), its ContextStatus (nil: none) and
+    # its stream (+emit+, nil: none), which gets an applied batch's ✂ row
+    # (LLMContextNotice).
+    Turn = Data.define(:conversation, :context, :emit) do
+      def initialize(emit: nil, **fields) = super
+    end
 
     # One output a call may name: its entry, its ToolIds ref, its tool,
     # its text (without the "[name]" lead) and its step; +offset+: what

data/lib/samagotchi/llm_context_notice.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "llm_context_stale"
+require_relative "tool_activity"
+require_relative "token_usage"
+
+module Samagotchi
+  # The ✂ row a turn gets for a batch of LLM context edits the apply rule
+  # let through (LLMContextApply::Outcome#applied?): the :llm_context_edited
+  # event both loops emit (KernelLoop#apply_llm_context!, its +emit+), at a
+  # request (+moment+ :request; a forget_outputs call's batch too) or at the
+  # end of a turn (:turn_end); never for the warm-up, a held or a staged
+  # batch, or a restore (the forget_outputs row says it). The web and the
+  # TUI print +text+ as it is; the web's hover lists +groups+.
+  #
+  # {type: :llm_context_edited, moment:, why:, freed_tokens:, tail_tokens:,
+  #  staged:, text: "✂ forgot 2 outputs, stubbed 1 stale read · frees ~4.1k
+  #  tokens (paid off)", groups: [{kind: "stale", items: [{id, tool, title,
+  #  note}]}, {kind: "forget", note:, by:, items: [{id, tool, title, kept}]}]}
+  #
+  # The stale items share one group, each with its own note; a forget group
+  # is one forget_outputs call's (the view's key: note, by and staged_at),
+  # its note once. Tokens are chars/4, so "~".
+  module LLMContextNotice
+    TYPE = :llm_context_edited
+    # A forget's note on the row, at most (the stub keeps all of it).
+    NOTE_MAX = 300
+    WHY = { payoff: "paid off", top_bucket: "the context is nearly full", turn_end: "at turn end" }.freeze
+
+    module_function
+
+    # @param outcome [LLMContextApply::Outcome] an applied one
+    # @param moment [Symbol] :request or :turn_end
+    # @return [Hash] the event
+    def event(conversation, outcome, moment:, cwd: Dir.pwd)
+      calls = LLMContextStale.paired_runs(conversation).to_h { |run| [run.ref.id, run.call] }
+      groups = groups(outcome.applied, calls, cwd)
+      freed = tokens(outcome.freed_chars)
+      { type: TYPE, moment: moment.to_s, why: outcome.why.to_s, freed_tokens: freed,
+        tail_tokens: tokens(outcome.tail_chars), staged: outcome.staged,
+        text: text(groups, freed, outcome.why, outcome.staged), groups: groups }
+    end
+
+    def groups(edits, calls, cwd)
+      stale = edits.select { |edit| edit.kind == :stale }
+      forgets = edits.select { |edit| edit.kind == :forget }.group_by { |edit| [edit.note, edit.by, edit.staged_at] }
+      groups = []
+      unless stale.empty?
+        groups << { kind: "stale", items: stale.map { |edit| item(edit, calls, cwd).merge(note: edit.note) } }
+      end
+      forgets.each do |(note, by, _), group|
+        items = group.map do |edit|
+          kept = edit.keep.map { |first, last| first == last ? first.to_s : "#{first}-#{last}" }
+          item(edit, calls, cwd).merge(kept: kept.empty? ? nil : kept.join(", ")).compact
+        end
+        groups << { kind: "forget", note: cut(note.to_s), by: by, items: items }
+      end
+      groups
+    end
+
+    # An output's id, its tool and its row's title (ToolActivity.tool_title;
+    # none when its call can't be told).
+    def item(edit, calls, cwd)
+      call = calls[edit.id]
+      return { id: edit.id } unless call
+
+      name = call[:name].to_s
+      { id: edit.id, tool: name, title: ToolActivity.tool_title(name, call, cwd: cwd) }.compact
+    end
+
+    # "✂ forgot 2 outputs, stubbed 1 stale read · frees ~4.1k tokens (paid
+    # off) · 1 more staged".
+    def text(groups, freed, why, staged)
+      forgot = groups.select { |group| group[:kind] == "forget" }.sum { |group| group[:items].size }
+      stale = groups.select { |group| group[:kind] == "stale" }.sum { |group| group[:items].size }
+      done = []
+      done << "forgot #{count(forgot, "output")}" if forgot.positive?
+      done << "stubbed #{count(stale, "stale read")}" if stale.positive?
+      frees = freed.positive? ? "frees ~#{k(freed)}" : "frees nothing"
+      frees += " (#{WHY[why]})" if WHY.key?(why)
+      line = "✂ #{done.join(", ")} · #{frees}"
+      staged.positive? ? "#{line} · #{staged} more staged" : line
+    end
+
+    def count(number, noun) = "#{number} #{noun}#{"s" unless number == 1}"
+
+    def tokens(chars) = [(chars / TokenUsage::CHARS_PER_TOKEN).ceil, 0].max
+
+    # "4.1k tokens", "640 tokens".
+    def k(tokens) = tokens >= 1000 ? format("%.1fk tokens", tokens / 1000.0) : "#{tokens} tokens"
+
+    def cut(note) = note.length > NOTE_MAX ? "#{note[0, NOTE_MAX - 1]}…" : note
+
+    private_class_method :groups, :item, :text, :count, :tokens, :k, :cut
+  end
+end