samagotchi 0.41.0 → 0.43.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.41.0
+version: 0.43.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/child_reports.rb

@@ -110,9 +110,13 @@ module Samagotchi
   # thread, the drain inside them).
   #
   # A turn takes reports (#take, at each boundary) and the worker settles
-  # them as the turn ends: #commit when it is kept (completed or canceled):
-  # the cursors move on (DelegateCursors) and the rings go; #release when it
-  # failed: the next turn reads the same rings again.
+  # them as the turn ends: #commit when the turn stays in the conversation
+  # (completed, canceled, or failed but kept: its work stayed, or a reminder
+  # or continue turn's): the cursors move on (DelegateCursors) and the rings
+  # go; #release when its end rolled it back (a failed turn that got
+  # nowhere, a canceled continue turn): the next turn reads the same rings
+  # again. So the model gets each report once (a later !rollback that
+  # erases a kept turn drops what it read, as before).
   class ChildReports
     SOURCE = Steer::DELEGATE_REPORT
 
@@ -178,7 +182,7 @@ module Samagotchi
       @taken = {}
     end
 
-    # The turn failed (rolled back): its rings stay for the next one.
+    # The turn was rolled back: its rings stay for the next one.
     def release
       @taken = {}
     end

data/lib/samagotchi/context_command.rb

@@ -75,7 +75,9 @@ module Samagotchi
     end
 
     # @param argv [Array<String>] the arguments after "context"
-    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, state_dir: nil, env: ENV, cwd: Dir.pwd)
+    # @param clock [#call] now, for ls's ages ("4s ago")
+    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, state_dir: nil, env: ENV, cwd: Dir.pwd,
+                   clock: -> { Time.now })
       @argv = argv.dup
       @stdin = stdin
       @stdout = stdout
@@ -83,6 +85,7 @@ module Samagotchi
       @state_dir = state_dir || Session.default_state_dir
       @env = env
       @cwd = cwd
+      @clock = clock
     end
 
     # @return [Integer] exit status: 0 done, 1 refused or failed, 2 usage
@@ -437,7 +440,7 @@ module Samagotchi
     def age(iso)
       return "-" unless iso
 
-      seconds = (Time.now - Time.iso8601(iso)).to_i
+      seconds = (@clock.call - Time.iso8601(iso)).to_i
       if seconds < 60 then "#{seconds}s ago"
       elsif seconds < 3600 then "#{seconds / 60}m ago"
       elsif seconds < 86_400 then "#{seconds / 3600}h ago"

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/engine.rb

@@ -54,6 +54,7 @@ require_relative "engine_peers"
 require_relative "bundle_needs"
 require_relative "model_overlay"
 require_relative "model_notes"
+require_relative "prompt_note"
 require_relative "served_model"
 require_relative "image_store"
 require_relative "vision_context"
@@ -478,6 +479,26 @@ module Samagotchi
                      muted: @muted_memory_names)
     end
 
+    # The model notes the session's prompt carried at its last build
+    # (Session#prompt_notes): a resumed session's or a woken worker's saved
+    # ones until this process builds its prompt; without a session, the
+    # notes the effective model's prompt would load.
+    # @return [Array<PromptNote>]
+    def prompt_notes
+      return @session.prompt_notes.dup if @session
+
+      model_notes.map { |note| PromptNote.from_note(note) }
+    rescue StandardError
+      []
+    end
+
+    # Records +notes+ (ModelNotes::Note) on the session as the ones its
+    # prompt carries; saved with it.
+    def record_prompt_notes(notes)
+      @session.prompt_notes = Array(notes).map { |note| PromptNote.from_note(note) } if @session && notes
+    end
+    private :record_prompt_notes
+
     # +name+'s resolved ref (ModelRef#ref).
     def model_ref_for(name)
       @host_registry.model_ref(name).ref
@@ -856,6 +877,9 @@ module Samagotchi
       @profile_resolution = nil
       sync_model_key!
       @prompt_builder.reset!
+      # The notes the new model's prompt loads at its next build, so /model,
+      # /stats and the web name them before the next turn does.
+      record_prompt_notes(model_notes) if @session
       sync_kernel_client!
       @client.invalidate_context_window!
       @metrics.forget_model_reports!
@@ -921,7 +945,8 @@ module Samagotchi
       snapshot = @metrics.snapshot
       target = @host_registry.resolve(@effective_model_name)
       served, served_for = served_model_for(snapshot, target: target)
-      snapshot = snapshot.merge(served_model: served, served_model_for: served_for, llm_context: llm_context_summary)
+      snapshot = snapshot.merge(served_model: served, served_model_for: served_for, llm_context: llm_context_summary,
+                                prompt_notes: prompt_notes.map(&:to_h))
       unless snapshot.dig(:context, :window_tokens)
         window = current_context_window(target)
         if window
@@ -1028,6 +1053,8 @@ module Samagotchi
     #   :metrics       [Hash]      @metrics.snapshot (per-session analytics)
     #   :pending_question [Hash, nil] current pending structured question
     #   :used_memory_names [Array<String>] deduped memory names active this session
+    #   :prompt_notes  [Array<Hash>] the model notes the prompt carried
+    #     ({name:, scope:, chars:, digest:}; #prompt_notes)
     #   :parent_id     [String, nil] the session that delegated this one
     #   :model_name    [String]    the model turns run on now (after /model)
     #   :served_model, :served_model_for [String, nil] what a generation of
@@ -1048,6 +1075,7 @@ module Samagotchi
         used_memory_names: @used_memories.names,
         preloaded_memory_names: preloaded_memory_names,
         muted_memory_names: @muted_memory_names.dup,
+        prompt_notes: prompt_notes.map(&:to_h),
         parent_id: @session&.parent_id,
         model_name: effective_model_ref,
         served_model: served_pair[0],
@@ -1462,6 +1490,8 @@ module Samagotchi
       prompt = @prompt_builder.build(chat: chat, thinking: level, layers: llm_context_layers(target))
       # The memory indexes this prompt holds: /stats, the snapshot, analytics.json.
       @metrics.memory_index = @prompt_builder.memory_index
+      # The model notes it carries: the session records them (/stats, /model, the web).
+      record_prompt_notes(@prompt_builder.prompt_notes)
       prompt
     end
 

data/lib/samagotchi/model_notes.rb

@@ -49,21 +49,24 @@ module Samagotchi
     # @param muted [Array<String>] the session's muted names (MutedMemories)
     # @param small [#call, nil] → whether the model is a small one; nil:
     #   guardrails.small_models (Guardrails::ModelSize)
+    # @param env [Hash] the XDG env the memories dirs resolve from
+    # @param warn [Boolean] false: no size warnings (a read-only report such
+    #   as chi self; the prompt's build gives them)
     # @return [Array<Note>]
-    def for(name:, key:, fallback_key: nil, muted: [], small: nil)
+    def for(name:, key:, fallback_key: nil, muted: [], small: nil, env: ENV, warn: true)
       return [] if name.nil? || name.to_s.strip.empty?
 
       small ||= -> { Guardrails::ModelSize.small?(name, key) }
       small_once = memo(small)
       seen = Set.new
       notes = SCOPES.flat_map do |scope|
-        files(scope).filter_map do |path|
+        files(scope, env).filter_map do |path|
           next unless seen.add?(File.expand_path(path))
 
           note_at(path, scope, name: name, key: key, fallback_key: fallback_key, muted: muted, small: small_once)
         end
       end
-      warn_sizes(notes)
+      warn_sizes(notes) if warn
       notes
     end
 
@@ -96,7 +99,7 @@ module Samagotchi
       @warn_mutex.synchronize { @warned.clear }
     end
 
-    def files(scope) = files_in(MemoryPaths.scope_dir(scope))
+    def files(scope, env = ENV) = files_in(MemoryPaths.scope_dir(scope, env: env))
 
     # The `model_notes_*.md` files in +dir+, by their names on disk: the
     # prefix exactly as written (a case-insensitive disk's glob matches

data/lib/samagotchi/plugin/attached_context.rb

@@ -27,27 +27,71 @@ module Samagotchi
       # +name+ and +cmd+ (+hint+, +every_seconds+). A source of that name
       # already attached stays as it is. One the user removed from the
       # session (its name, or its URL) isn't attached again (#declined?)
-      # until the user adds it again.
+      # until the user adds it again, or +force+: the user's own explicit
+      # choice (a click), which clears the declined marker (by the name,
+      # and by the URL).
       # @return [String, nil] the source's name; nil when declined
       # @raise [Error]
-      def attach(url: nil, name: nil, cmd: nil, why: nil, hint: nil, every_seconds: nil)
-        own = location or raise Error, "this session has no id yet"
+      def attach(url: nil, name: nil, cmd: nil, why: nil, hint: nil, every_seconds: nil, force: false)
+        own = own_location!
         source = url ? from_url(url, name: name, why: why) : from_cmd(name: name, cmd: cmd, why: why, hint: hint, every_seconds: every_seconds)
-        return nil if own.declined?(source.name) || (url && own.declined_hints.include?(source.hint))
+        if force
+          own.undecline(source.name, hint: url && source.hint)
+        elsif own.declined?(source.name) || (url && own.declined_hints.include?(source.hint))
+          return nil
+        end
         return source.name if own.source(source.name)
 
-        own.add(source.with(scope: own.scope))
-        source.name
+        add(own, source)
       rescue ContextSources::Invalid, ContextProviders::Invalid => e
         raise Error, e.message
       end
 
-      # Whether the user removed +name+ from this session (so #attach skips it).
-      def declined?(name)
-        own = location
-        own ? own.declined?(name) : false
+      # Marks +name+ (or +url+'s source, through its provider) declined in
+      # this session, as the user's removal does: #attach skips it until the
+      # user adds it again. An attached source stays (chi context rm).
+      # @return [String] the name
+      # @raise [Error]
+      def decline(url: nil, name: nil)
+        own = own_location!
+        if url
+          resolved = ContextProviders.resolve(url) or raise Error, "no installed bundle resolves #{url}"
+          name = name ? ContextSources.check_name!(name) : resolved.name
+          hint = resolved.hint
+        else
+          raise Error, "give url: or name:" if name.to_s.empty?
+
+          name = ContextSources.check_name!(name)
+        end
+        own.decline(name, hint)
+        name
+      rescue ContextSources::Invalid, ContextProviders::Invalid => e
+        raise Error, e.message
+      end
+
+      # Whether the user removed +name+ (or +url+) from this session (so
+      # #attach skips it).
+      def declined?(name = nil, url: nil)
+        own = location or return false
+        name_declined?(own, name) || (!url.to_s.empty? && own.declined_hints.include?(url))
+      end
+
+      # Records that this plugin offered +name+ (+hint+: its URL; +why+: the
+      # reason an attach from the offer gives) here, so a worker restart
+      # doesn't offer it again.
+      # @return [ContextSources::Offer]
+      # @raise [Error]
+      def mark_offered(name, hint, why: nil)
+        own_location!.mark_offered(name, hint, why: why)
+      rescue ContextSources::Invalid => e
+        raise Error, e.message
+      end
+
+      # @return [ContextSources::Offer, nil] the offer #mark_offered recorded
+      def offered(name)
+        location&.offered(name)
       rescue ContextSources::Invalid
-        false
+        nil
       end
 
       # This session's sources (its own, then its project's).
@@ -69,6 +113,26 @@ module Samagotchi
 
       def state_dir = @host.state_dir&.call || Session.default_state_dir
 
+      # Two attaches at once (a double click): the one that lost the race
+      # finds the source there and returns its name too.
+      def add(own, source)
+        own.add(source.with(scope: own.scope))
+        source.name
+      rescue ContextSources::Invalid
+        raise unless own.source(source.name)
+
+        source.name
+      end
+
+      # An invalid name isn't declined (and doesn't hide the URL's check).
+      def name_declined?(own, name)
+        !name.nil? && own.declined?(name)
+      rescue ContextSources::Invalid
+        false
+      end
+
+      def own_location! = location || raise(Error, "this session has no id yet")
+
       def location
         id = @host.session_id.call
         id && ContextSources.session_location(id, state_dir: state_dir)

data/lib/samagotchi/prompt_note.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # A model note a session's system prompt carried (ModelNotes::Note
+  # without its body): what the session file's `prompt_notes` records at
+  # each prompt build, so /stats, /model, the web and a later comparison
+  # read what the prompt really held. name: the memory name; scope:
+  # "system" or "project"; chars: the body's length in the prompt; digest:
+  # a short SHA-256 of that body (ModelNotes::Note#digest).
+  PromptNote = Data.define(:name, :scope, :chars, :digest) do
+    # @param note [ModelNotes::Note]
+    def self.from_note(note)
+      new(name: note.name, scope: note.scope, chars: note.chars, digest: note.digest)
+    end
+
+    # A saved or wire record (string or symbol keys); nil without a name.
+    def self.from_h(raw)
+      return raw if raw.is_a?(PromptNote)
+      return nil unless raw.is_a?(Hash)
+
+      get = ->(key) { raw.key?(key.to_s) ? raw[key.to_s] : raw[key] }
+      name = get.call(:name).to_s.strip
+      return nil if name.empty?
+
+      chars = get.call(:chars)
+      new(name: name, scope: get.call(:scope)&.to_s, chars: chars.is_a?(Numeric) ? chars.to_i : nil,
+          digest: get.call(:digest)&.to_s)
+    end
+
+    # The records of a saved list (others dropped).
+    # @return [Array<PromptNote>]
+    def self.list(raw)
+      Array(raw).filter_map { |entry| from_h(entry) }
+    end
+
+    # "model_notes_deepseek (system, 612 chars), model_notes_x (project,
+    # 80 chars)": the line /model, /stats and chi self show; "" without
+    # notes. As format.js promptNotesText (spec/shared/labels_matrix.json).
+    # @param notes [Array<PromptNote, Hash>]
+    def self.text(notes)
+      list(notes).map(&:label).join(", ")
+    end
+
+    # "model_notes_deepseek (system, 612 chars)".
+    def label
+      details = [scope, chars && "#{chars} chars"].compact.reject { |part| part.to_s.empty? }
+      details.empty? ? name : "#{name} (#{details.join(", ")})"
+    end
+
+    # The session file's record (string keys).
+    def to_file = to_h.transform_keys(&:to_s)
+  end
+end