samagotchi 0.30.0 → 0.32.0

data/lib/samagotchi/guardrails/verdict.rb

@@ -5,9 +5,17 @@ module Samagotchi
     # The gate's verdict for one tool call. Voters (hooks now, rules later)
     # call #deny! or #ask!; the strictest vote wins (deny > ask > allow) and
     # a vote never relaxes it, so a deny is sticky. Of two equal votes the
-    # first one stays.
+    # first one stays, except that a protected rule's ask (PROTECTED_RULES)
+    # takes over an unprotected ask: its rule id is what a parent's answer
+    # and a stored approval are checked against, and the offered scopes
+    # narrow to both asks' common ones.
     class Verdict
       STRICTNESS = { allow: 0, ask: 1, deny: 2 }.freeze
+      # Rules that ask about chi's own config and hooks: the core
+      # ProtectedPaths asks and the guardrails bundle's shell rule; and a
+      # command source for attached context (it runs later, ungated). Only
+      # the user may allow them (ParentApprovals).
+      PROTECTED_RULES = %w[chi-config chi-hooks shell-touches-chi chi-context-cmd].freeze
       SCOPES = %w[once session repo rule].freeze
       DO_NOT_RETRY = "Do not retry it or reach the same result another way; ask the user how to proceed."
 
@@ -46,13 +54,18 @@ module Samagotchi
       # @param scopes [Array<String>, nil] which approval scopes the user may
       #   pick (default all of SCOPES)
       def ask!(reason, scopes: nil, rule: nil, source: nil, decided_by: "hook")
+        earlier = ask? ? @scopes : nil
         return self unless vote(:ask, reason, rule: rule, source: source, decided_by: decided_by)
 
         picked = Array(scopes).map(&:to_s) & SCOPES
-        @scopes = picked.empty? ? SCOPES : picked
+        picked = SCOPES if picked.empty?
+        picked &= earlier if earlier
+        @scopes = picked.empty? ? %w[once] : picked
         self
       end
 
+      def self.protected_rule?(rule) = PROTECTED_RULES.include?(rule.to_s)
+
       # A before_tool_call hook set the old event[:blocked] flag. Its model
       # text stays "blocked by guardrail: <reason>".
       def legacy_deny!(reason)
@@ -118,7 +131,7 @@ module Samagotchi
       end
 
       def vote(decision, reason, decided_by:, rule: nil, source: nil)
-        return false unless STRICTNESS.fetch(decision) > STRICTNESS.fetch(@decision)
+        return false unless STRICTNESS.fetch(decision) > STRICTNESS.fetch(@decision) || takes_over?(decision, rule)
 
         @decision = decision
         @reason = reason.to_s.strip
@@ -129,6 +142,11 @@ module Samagotchi
         @legacy = false
         true
       end
+
+      # A protected rule's ask over an unprotected one.
+      def takes_over?(decision, rule)
+        decision == :ask && ask? && Verdict.protected_rule?(rule) && !Verdict.protected_rule?(@rule)
+      end
     end
   end
 end

data/lib/samagotchi/idle_recap.rb

@@ -54,6 +54,7 @@ module Samagotchi
       TOOL_OUTPUT_HEADER_RE = /\A\[([\w.:-]+)\]/
       # The text the web sends for a turn of images alone (images.js turnText).
       IMAGE_ONLY_RE = /\A\s*(?:\[image: [^\]\n]*\]\s*)+\z/
+      DELEGATE_REPORT_LINE = "(a delegate session's report, delivered by chi; not the user's words)"
 
       module_function
 
@@ -71,6 +72,9 @@ module Samagotchi
             # An image is a line naming it (refs only, never its bytes), unless
             # the text is only the web's placeholder naming it already.
             content = message["content"].to_s
+            # A delegate child's report (ChildReports) is chi's news, not
+            # what the user said.
+            content = "#{DELEGATE_REPORT_LINE}\n#{content}" if message["source"].to_s == Steer::DELEGATE_REPORT
             images = IMAGE_ONLY_RE.match?(content) ? [] : image_lines(message["images"])
             [content, *images].reject(&:empty?).join("\n")
           when "model", "assistant"

data/lib/samagotchi/kernel_loop.rb

@@ -97,6 +97,8 @@ module Samagotchi
 
     DEFAULT_MAX_TOOL_OUTPUT_CHARS = 10_000
     QWEN_INCOMPLETE_TOOL_CALL_RECOVERY_LIMIT = 2
+    # How much of a malformed generation's end the warning keeps.
+    MALFORMED_TAIL_CHARS = 400
     QWEN_INCOMPLETE_TOOL_CALL_RECOVERY_PROMPT = "Continue the previous assistant message by finishing the open <tool_call> XML block. Output only the remaining XML needed to complete the tool call."
 
     # @param tools [Tools::Registry, nil] the tools calls dispatch to (the
@@ -242,7 +244,8 @@ module Samagotchi
     # the prefill, and what the caller gave.
     Turn = Struct.new(:conversation, :context, :empty_retry, :tool_activity, :buffer, :streamed_thinking, :qwen_attempts,
                       :qwen_partial, :prefill, :pending_tool_calls, :model_name, :pending_input, :on_stream_event,
-                      :cancel_controller, :cap, :emit, :iteration, :empty_steps, :ended_empty, keyword_init: true)
+                      :cancel_controller, :cap, :emit, :iteration, :empty_steps, :ended_empty, :malformed_retried,
+                      :uncached_next, keyword_init: true)
     # One request: the prompt and its images as sent, the images' token
     # estimate, and the window it was measured against.
     Request = Struct.new(:prompt, :images, :image_tokens, :window, :prefill, keyword_init: true)
@@ -250,9 +253,10 @@ module Samagotchi
     # generation's own server counts, the model the server named, the
     # thinking it streamed, and why it stopped (the transport's finish
     # reason, Client::Transport#finish_reason_from; nil when not named),
-    # and its prompt-cache counts (the largest seen: they come cumulative).
+    # and its prompt-cache counts (the largest seen: they come cumulative),
+    # and where its visible text starts in the turn's buffer.
     Generation = Struct.new(:response, :cut, :usage, :served_model, :streamed_thinking, :finish_reason, :cache,
-                            keyword_init: true)
+                            :buffer_mark, keyword_init: true)
     private_constant :Turn, :Request, :Generation
 
     def start_turn(messages, on_stream_event:, cancel_controller:, pending_input:, cap:)
@@ -278,6 +282,9 @@ module Samagotchi
       request = prepare_request(turn)
       generation = generate(turn, request)
       return after_cut(turn, generation) if generation.cut
+      if (reason = parser.malformed(generation.response))
+        return after_malformed(turn, generation, reason)
+      end
 
       turn.conversation << { role: "model", content: request.prefill + generation.response.to_s }
       # Profile-specific parse (incl. Qwen unterminated-block recovery); the
@@ -330,10 +337,13 @@ module Samagotchi
       # thinking_chars=N content_length=…).
       generation = Generation.new(usage: nil, served_model: nil, streamed_thinking: 0)
       fire_hook(:before_generation, { type: :before_generation, iteration: turn.iteration }) if @hooks
-      buffer_mark = turn.buffer.length
+      buffer_mark = generation.buffer_mark = turn.buffer.length
       # A cancel salvages only this generation's thinking: the earlier
       # steps' is on their own messages already.
       turn.streamed_thinking = +""
+      # Only the retry of a malformed generation skips the prompt cache.
+      uncached = turn.uncached_next
+      turn.uncached_next = false
       generation.response = with_generation(turn.cancel_controller) do |generation_controller|
         request_generation(
           request.prompt,
@@ -341,6 +351,7 @@ module Samagotchi
           cancel_controller: turn.cancel_controller,
           model_name: turn.model_name,
           sampling: turn.empty_retry.request_sampling(@turn_settings.sampling),
+          cache_prompt: !uncached,
           on_chunk: ->(chunk) { stream_chunk(turn, generation, stream_splitter, chunk) },
           on_retry: lambda { |retry_event|
             # The retry streams from the start: its counts replace these.
@@ -462,6 +473,31 @@ module Samagotchi
       cancelled_result(turn.conversation, tool_activity: turn.tool_activity, reason: :hook, partial_assistant_text: "")
     end
 
+    # A corrupt generation (ToolCallParser#malformed) is no answer and runs
+    # no tool: it is logged and dropped, with its streamed text, and the
+    # same prompt goes once more without the server's prompt cache (a
+    # poisoned cache made it, ggml-org/llama.cpp#27148), shown as the loop
+    # asking again. A second one fails the turn. Returns :next.
+    def after_malformed(turn, generation, reason)
+      response = generation.response.to_s
+      Log.warn(:model, "generation_malformed", iteration: turn.iteration, reason: reason, id_slot: @last_slot,
+                                               cache_n: generation.cache&.dig(:cached), finish_reason: generation.finish_reason,
+                                               retried: turn.malformed_retried ? true : false,
+                                               payload: response[-MALFORMED_TAIL_CHARS..] || response)
+      turn.buffer.slice!(generation.buffer_mark..)
+      if turn.malformed_retried
+        label = @client.respond_to?(:host_name) && @client.host_name ? @client.host_name : "llama.cpp"
+        raise LLM::MalformedGeneration.new("#{label}: #{reason}, again without the prompt cache; nothing was saved",
+                                           host: label)
+      end
+
+      turn.malformed_retried = true
+      turn.uncached_next = true
+      emit(turn, type: :empty_answer_retry, iteration: turn.iteration, attempt: 1, of: 1,
+                 finish_reason: generation.finish_reason, malformed: true)
+      :next
+    end
+
     # A generation with no tool calls: a Qwen call left open is asked to be
     # finished; an empty answer is asked again (EmptyAnswerRetry: not when
     # a length stop came with the context full); queued input keeps the
@@ -612,8 +648,11 @@ module Samagotchi
     end
 
     # +sampling+: this request's (EmptyAnswerRetry#request_sampling).
-    def complete_kwargs(cancel_controller:, model_name: nil, on_chunk: nil, on_retry: nil, images: [], sampling: nil)
+    # +cache_prompt+: false for a malformed generation's retry (only then sent).
+    def complete_kwargs(cancel_controller:, model_name: nil, on_chunk: nil, on_retry: nil, images: [], sampling: nil,
+                        cache_prompt: true)
       kwargs = {}
+      kwargs[:cache_prompt] = false unless cache_prompt
       # Only a request with images names them: a text-only call is unchanged.
       kwargs[:images] = images unless images.empty?
       kwargs[:on_chunk] = on_chunk if on_chunk

data/lib/samagotchi/llm/chat_loop.rb

@@ -213,7 +213,7 @@ module Samagotchi
       # Array), plus a model turn's tool_calls and thinking (the host's
       # reasoning, never sent back), a result's tool_call_id, the image
       # refs of a user message or a tool result, a prompt's turn_id (Engine,
-      # never sent), and a plugin tool result's tool_params and tool_labels
+      # never sent) and a wake turn's report's turn_start (Steer, never sent), and a plugin tool result's tool_params and tool_labels
       # (the live row's params line and label, never sent back), an
       # edit/write result's tool_diffs (never sent), and an empty-answer
       # note's marker (TurnNote.empty, never sent).
@@ -225,6 +225,7 @@ module Samagotchi
           message[:tool_call_id] = entry[:tool_call_id] if entry[:tool_call_id]
           message[:images] = entry[:images] if entry[:images].is_a?(Array) && !entry[:images].empty?
           message[:turn_id] = entry[:turn_id] if entry[:turn_id]
+          message[:turn_start] = true if entry[:turn_start] == true
           message[:thinking] = entry[:thinking] if entry[:thinking].is_a?(String) && !entry[:thinking].empty?
           ToolResponse::SAVED_KEYS.each { |key| message[key] = entry[key] if entry[key] }
           message[TurnNote::RETRY_NUDGE] = true if TurnNote.retry_nudge?(entry)

data/lib/samagotchi/llm/errors.rb

@@ -207,6 +207,15 @@ module Samagotchi
       def summary = "unexpected response from host #{host}: #{detail}"
     end
 
+    # A native generation that came out corrupt twice (KernelLoop: a tool
+    # call never closed, or a fresh thought header after the answer), the
+    # second time without the server's prompt cache. A poisoned llama.cpp
+    # prompt cache does this (ggml-org/llama.cpp#27148); the text is not
+    # an answer.
+    class MalformedGeneration < ProtocolError
+      def summary = "malformed generation from host #{host}: #{detail}"
+    end
+
     # A request that kept failing on network errors until the retry budget
     # ran out (or failed mid-stream, where a retry would repeat output).
     class RetryExhausted < ConnectionError

data/lib/samagotchi/log_line.rb

@@ -16,7 +16,7 @@ module Samagotchi
   # (debug dumps) are indented by four spaces and belong to the record above.
   module LogLine
     LEVELS = %w[DEBUG INFO WARN ERROR].freeze
-    TAGS = %w[turn http worker bridge web attached repl idle recap hooks plugins guardrails config memory model].freeze
+    TAGS = %w[turn http worker bridge web attached repl idle recap hooks plugins guardrails config memory model context].freeze
     INDENT = "    "
 
     Record = Struct.new(:ts, :level, :tag, :pid, :sid, :event, :fields, :payload, keyword_init: true)

data/lib/samagotchi/log_subscriber.rb

@@ -29,7 +29,7 @@ module Samagotchi
       question_cancelled: %i[id reason],
       question_relay: %i[id reason],
       generation_cancelled: %i[iteration],
-      empty_answer_retry: %i[iteration attempt of finish_reason thinking_chars stopped_by]
+      empty_answer_retry: %i[iteration attempt of finish_reason thinking_chars stopped_by malformed]
     }.freeze
 
     # @param session_id [#call] the session the events are about (the

data/lib/samagotchi/memory_bundle/installer.rb

@@ -302,6 +302,8 @@ module Samagotchi
         # ── Plugin: <file> into <bundle_dir>/plugin/ (docs/plugins.md) ────
         # Like the rules, the bundle's plugin replaces an earlier one.
         plugin_file_for_provenance = install_plugin(manifest, normalized_dir, provenance)
+        # ── Scripts: scripts/<file> into <bundle_dir>/scripts/ ────────────
+        scripts_for_provenance = install_scripts(manifest, normalized_dir, provenance)
         warn_hooks_requires_chi(manifest, all_hooks_in_bundle)
         warn_rules_requires_chi(manifest, incoming_rules)
 
@@ -417,7 +419,9 @@ module Samagotchi
             plugin_file: plugin_file_for_provenance,
             requires_chi: manifest.requires_chi,
             needs: manifest.needs,
-            conflicts: @conflicts.keys
+            conflicts: @conflicts.keys,
+            scripts_files: scripts_for_provenance,
+            context_providers: manifest.context_providers
           )
         end
 
@@ -615,6 +619,44 @@ module Samagotchi
         dest
       end
 
+      # The manifest's scripts, copied into <bundle_dir>/scripts/ (the
+      # folder replaced: a script the new version dropped goes). A declared
+      # sha256 that differs warns, as a plugin's does.
+      # @return [Hash{String => String}] file name => installed path
+      def install_scripts(manifest, source_dir, provenance)
+        scripts = manifest&.scripts || {}
+        scripts.each_key do |file|
+          next if File.file?(File.join(source_dir, "scripts", file))
+
+          raise InstallError, "the manifest names scripts/#{file}, which the bundle doesn't have"
+        end
+        return {} if @dry_run
+
+        unchanged = scripts.keys.select do |file|
+          dest = File.join(provenance.scripts_dir, file)
+          File.file?(dest) && FileUtils.identical?(File.join(source_dir, "scripts", file), dest)
+        end
+        FileUtils.rm_rf(provenance.scripts_dir)
+        return {} if scripts.empty?
+
+        FileUtils.mkdir_p(provenance.scripts_dir)
+        scripts.to_h do |file, declared|
+          dest = File.join(provenance.scripts_dir, file)
+          FileUtils.cp(File.join(source_dir, "scripts", file), dest)
+          @results["scripts/#{file}"] = if unchanged.include?(file) then { status: "skipped", reason: "already up to date" }
+                                        elsif @upgrade && provenance.read then { status: "updated" }
+                                        else { status: "installed" }
+                                        end
+          FileUtils.chmod(0o755, dest)
+          actual = Digest::SHA256.hexdigest(File.binread(dest))
+          expected = declared.to_s.delete_prefix("sha256:")
+          if @strict && !expected.empty? && actual != expected
+            @warnings << "Checksum mismatch for script #{file}: expected #{expected[0..7]}..., got #{actual[0..7]}..."
+          end
+          [file, dest]
+        end
+      end
+
       # A model overlay (<name>.<key>.md, docs/memory.md) loads only with
       # its base, under the matching model: it gets no index line (every
       # model would see it as a memory of its own). Its base is looked for

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -3,6 +3,7 @@
 require "yaml"
 require "digest"
 require "fileutils"
+require_relative "../context_providers"
 
 module Samagotchi
   module MemoryBundle
@@ -25,6 +26,15 @@ module Samagotchi
     #       why: reads PRs     #   optional
     #       hint: brew install gh   # optional
     #     - jq                 #   short form: just the command
+    #   scripts:               # optional — files in scripts/ a context
+    #     pr_context.rb: sha256:…   #   provider's command runs (installed into
+    #                          #   the bundle's own dir, scripts/)
+    #   context_providers:     # optional — URL → attached context source
+    #     - match: '\Ahttps://…/pull/(\d+)'   # (ContextProviders)
+    #       name: 'pr-\1'
+    #       cmd: '{ruby} {bundle_dir}/scripts/pr_context.rb {url}'
+    #       why: GitHub PR      #   optional
+    #       every_seconds: 300  #   optional
     #   includes: [a, b]       # optional — a profile (meta bundle): the
     #                          #   shipped bundles it installs; its dir holds
     #                          #   only manifest.yml (MemoryBundle::Profile)
@@ -33,12 +43,15 @@ module Samagotchi
 
       # A plugin file is a plain .rb name in the bundle's top directory.
       PLUGIN_FILE = /\A[A-Za-z0-9_][A-Za-z0-9_.-]*\.rb\z/
+      # A script is a plain file name in the bundle's scripts/.
+      SCRIPT_FILE = /\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/
       # A need is a plain executable name: no path, no spaces.
       NEED_COMMAND = /\A[A-Za-z0-9][A-Za-z0-9._+-]*\z/
       # A bundle name, as `chi bundle install <name>` takes a shipped one.
       BUNDLE_NAME = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/
 
-      attr_reader :name, :version, :scope, :description, :files, :hooks, :trust_level, :plugin, :requires_chi, :needs, :includes
+      attr_reader :name, :version, :scope, :description, :files, :hooks, :trust_level, :plugin, :requires_chi, :needs, :includes,
+                  :scripts, :context_providers
 
       def initialize(path:)
         @path = path
@@ -53,6 +66,8 @@ module Samagotchi
         @plugin = parse_plugin(raw["plugin"])
         @requires_chi = parse_requires_chi(raw["requires_chi"])
         @needs = self.class.parse_needs(raw["needs"])
+        @scripts = parse_scripts(raw["scripts"])
+        @context_providers = parse_context_providers(raw["context_providers"])
         @includes = parse_includes(raw["includes"])
       end
 
@@ -213,6 +228,27 @@ module Samagotchi
         { file: file, sha256: sha }
       end
 
+      # scripts: {file => sha256} → the same, "sha256:" prefixed; {} when absent.
+      def parse_scripts(raw)
+        return {} if raw.nil?
+        raise ValidationError, "scripts: must be a mapping of file name to sha256" unless raw.is_a?(Hash)
+
+        raw.to_h do |file, sha|
+          file = file.to_s
+          raise ValidationError, "scripts: #{file.inspect} isn't a plain file name in scripts/" unless file.match?(SCRIPT_FILE)
+
+          sha = sha.to_s.strip
+          [file, sha.empty? || sha.start_with?("sha256:") ? sha : "sha256:#{sha}"]
+        end
+      end
+
+      # @return [Array<ContextProviders::Provider>]
+      def parse_context_providers(raw)
+        ContextProviders.parse_list(raw)
+      rescue ContextProviders::Invalid => e
+        raise ValidationError, e.message
+      end
+
       # includes: → the names in order, duplicates dropped; [] when absent.
       # A meta ships nothing of its own, so files, hooks or a plugin next
       # to it is a ValidationError.
@@ -226,8 +262,8 @@ module Samagotchi
 
           name
         end.uniq
-        if !names.empty? && (!@files.empty? || !@hooks.empty? || @plugin)
-          raise ValidationError, "a bundle with includes: holds only its includes (no files, hooks or plugin)"
+        if !names.empty? && (!@files.empty? || !@hooks.empty? || @plugin || !@scripts.empty?)
+          raise ValidationError, "a bundle with includes: holds only its includes (no files, hooks, plugin or scripts)"
         end
 
         names

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -39,6 +39,12 @@ module Samagotchi
         File.join(@bundle_dir, "plugin")
       end
 
+      # The installed scripts' dir (scripts/<file>): what a context
+      # provider's command finds as {bundle_dir}/scripts.
+      def scripts_dir
+        File.join(@bundle_dir, "scripts")
+      end
+
       # The plugin file as installed, or nil when the bundle has none.
       def plugin_path(data = read)
         file = data && data[:plugin].is_a?(Hash) ? data[:plugin][:file].to_s : ""
@@ -129,8 +135,12 @@ module Samagotchi
       #   edits that conflict with it; their entries get conflict: true
       # @param includes [Array<String>, nil] a profile's recorded members
       #   (MemoryBundle::Profile); nil for a plain bundle
+      # @param scripts_files [Hash] file name => installed script; the
+      #   sha256 of each is recorded (ContextFetch checks it before a run)
+      # @param context_providers [Array<ContextProviders::Provider>]
       def write(files:, scope:, version:, source_path:, hooks: {}, trust_level: nil, source_commit: nil, hooks_files: {},
-                guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil, conflicts: [], includes: nil)
+                guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil, conflicts: [], includes: nil,
+                scripts_files: {}, context_providers: [])
         FileUtils.mkdir_p(@bundle_dir)
         bases_dir = File.join(@bundle_dir, "bases")
         FileUtils.mkdir_p(bases_dir)
@@ -241,6 +251,12 @@ module Samagotchi
         manifest_data["requires_chi"] = requires_chi.to_s if requires_chi && !requires_chi.to_s.empty?
         manifest_data["needs"] = needs.map { |n| n.transform_keys(&:to_s).compact } if needs.is_a?(Array) && !needs.empty?
         manifest_data["includes"] = includes.map(&:to_s) if includes.is_a?(Array)
+        unless scripts_files.empty?
+          manifest_data["scripts"] = scripts_files.sort.to_h do |file, path|
+            [file.to_s, { "sha256" => "sha256:#{Digest::SHA256.hexdigest(File.binread(path.to_s))}" }]
+          end
+        end
+        manifest_data["context_providers"] = context_providers.map(&:to_h) unless context_providers.empty?
 
         write_manifest(manifest_data)
       end

data/lib/samagotchi/plugin/attached_context.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "../context_sources"
+require_relative "../context_providers"
+require_relative "../session"
+
+module Samagotchi
+  module Plugin
+    # ctx.context (docs/plugins.md, Attached context): context a plugin
+    # attaches to its session (ContextSources), through an installed
+    # bundle's provider (a URL) or as its own command. In-process, like any
+    # plugin code: not gated as `chi context add --cmd` through execute is.
+    # The session's worker runs and absorbs it (ContextPoller).
+    class AttachedContext
+      # An attach that couldn't be done; the message says why.
+      class Error < StandardError; end
+
+      # @param host [Host] session_id and state_dir
+      def initialize(host, bundle:)
+        @host = host
+        @bundle = bundle
+      end
+
+      # Attach a source to this session. +url+: through an installed
+      # bundle's provider (+name+ and +why+ replace the provider's); else
+      # +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.
+      # @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"
+        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))
+        return source.name if own.source(source.name)
+
+        own.add(source.with(scope: own.scope))
+        source.name
+      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
+      rescue ContextSources::Invalid
+        false
+      end
+
+      # This session's sources (its own, then its project's).
+      # @return [Array<Hash>] {name:, scope:, why:, hint:, fetched_at:, error:, provider:}
+      def list
+        id = @host.session_id.call
+        return [] unless id
+
+        session = Session.load(id, state_dir: state_dir)
+        ContextSources.attached(id, project_root: session.project_root, state_dir: state_dir).map do |attached|
+          snapshot = attached.snapshot
+          { name: attached.name, scope: attached.location.scope, why: attached.source.why,
+            hint: snapshot.hint || attached.source.hint, fetched_at: snapshot.fetched_at, error: snapshot.error,
+            provider: attached.source.provider }
+        end
+      end
+
+      private
+
+      def state_dir = @host.state_dir&.call || Session.default_state_dir
+
+      def location
+        id = @host.session_id.call
+        id && ContextSources.session_location(id, state_dir: state_dir)
+      end
+
+      def from_url(url, name:, why:)
+        resolved = ContextProviders.resolve(url) or raise Error, "no installed bundle resolves #{url}"
+        source(name: name ? ContextSources.check_name!(name) : resolved.name, cmd: resolved.cmd, why: why || resolved.why,
+               hint: resolved.hint, every_seconds: resolved.every_seconds, provider: resolved.bundle)
+      end
+
+      def from_cmd(name:, cmd:, why:, hint:, every_seconds:)
+        raise Error, "give url: or cmd: (with name:)" if cmd.to_s.strip.empty?
+
+        source(name: ContextSources.check_name!(name), cmd: cmd.to_s, why: why, hint: hint,
+               every_seconds: ContextSources.check_every!(every_seconds), provider: nil)
+      end
+
+      def source(name:, cmd:, why:, hint:, every_seconds:, provider:)
+        ContextSources::Source.new(
+          name: name, cmd: cmd, every_seconds: every_seconds,
+          why: ContextSources.one_line(why, ContextSources::LINE_MAX_CHARS),
+          hint: ContextSources.one_line(hint, ContextSources::LINE_MAX_CHARS), scope: nil,
+          added_by: "plugin:#{@bundle}", created_at: Time.now.utc.iso8601, provider: provider
+        )
+      end
+    end
+  end
+end

data/lib/samagotchi/plugin/context.rb

@@ -7,6 +7,7 @@ require_relative "../guardrails/context"
 require_relative "../idle_client"
 require_relative "side_question"
 require_relative "sessions"
+require_relative "attached_context"
 
 module Samagotchi
   module Plugin
@@ -98,6 +99,20 @@ module Samagotchi
       #   current_model_only names it
       def model_key = @host.model_key&.call
 
+      # Whether the session is a `chi scratch` one (deleted when it ends).
+      def scratch? = !!@host.scratch&.call
+
+      # Whether the session is a delegate child (Session#delegate?): a task
+      # another session handed over, not the user's own.
+      def delegate?
+        id = session_id
+        return false unless id
+
+        Session.load(id, state_dir: @host.state_dir&.call || Session.default_state_dir).delegate?
+      rescue ArgumentError
+        false
+      end
+
       # @return [String] the session's working directory
       def cwd = @host.cwd.call || Dir.pwd
 
@@ -210,6 +225,13 @@ module Samagotchi
         @sessions ||= Sessions.new(@host)
       end
 
+      # This session's attached context: attach a URL or a command, list
+      # (AttachedContext).
+      # @return [AttachedContext]
+      def context
+        @context ||= AttachedContext.new(@host, bundle: @bundle)
+      end
+
       # A single-select question through the question flow. Inside a
       # stream hook's handler (generation_progress) it asks no one (nil).
       # @return [Hash, nil] {selected:, freeform:, selected_indices:}, or nil

data/lib/samagotchi/prompt_warmup.rb

@@ -20,9 +20,18 @@ module Samagotchi
   #   another slot (12 s);
   # - once the warm-up is done, nothing is pinned: the server finds the
   #   state itself, and pinning to a slot it has since cleared skips its
-  #   prompt cache (12 s again). #take_pin forgets the slot either way.
+  #   prompt cache (12 s again). #take_pin forgets the slot either way;
+  # - no warm-up when /slots says that slot is busy (Client#slot_status):
+  #   another session took it (a delegate child, often), and llama.cpp
+  #   defers a pinned request until the slot is free, so the warm-up and
+  #   then this session's next turn would wait out that generation. The
+  #   next request then goes unpinned, and the server's prompt cache
+  #   restores the state. When /slots can't say, the warm-up runs.
   class PromptWarmup
     MODES = %w[auto off].freeze
+    # Seconds #take_pin waits for the busy-slot check (Client#slot_status
+    # gives up within 3 s).
+    DECIDE_TIMEOUT = 3
 
     # Whether cache.warmup allows a warm-up (auto, the default; off, false,
     # no or 0 turn it off; anything else warns once and is auto).
@@ -52,8 +61,15 @@ module Samagotchi
     #   nothing to pin the next request to)
     # @return [Thread]
     def start(client:, prompt:, model:, slot:, images: [])
+      # Whether the warm-up went to its slot (true) or was skipped: the
+      # first value pushed is the answer.
+      sent = Queue.new
       thread = Thread.new do
         Thread.current.report_on_exception = false
+        busy = slot.is_a?(Integer) && client.slot_status(slot, model: model) == :busy
+        sent << !busy
+        next skip(slot) if busy
+
         result = client.warm_up(prompt, model: model, slot: slot, images: images)
         Log.info(:model, "warmup", slot: result&.slot, cached: result&.cache_n, prefilled: result&.prompt_n,
                                    prefill_ms: result&.prompt_ms, chars: prompt.length)
@@ -61,25 +77,34 @@ module Samagotchi
       rescue StandardError => e
         Log.warn(:model, "warmup_failed", error: e.class.name, msg: e.message.to_s[0, 200])
         nil
+      ensure
+        sent << false
       end
       @mutex.synchronize do
         @thread = thread
-        @state = { thread: thread, client: client, slot: slot }
+        @state = { thread: thread, client: client, slot: slot, sent: sent }
       end
       thread
     end
 
     # The slot the next request on +client+ must run on: the warm-up's,
-    # while it still runs there; nil otherwise (done, failed, unpinned, or
-    # another host). Called once per request; the first call forgets the
-    # warm-up, so no later request is ever pinned.
+    # while it still runs there; nil otherwise (done, failed, skipped,
+    # unpinned, or another host). Called once per request; the first call
+    # forgets the warm-up, so no later request is ever pinned. Waits for
+    # the busy-slot check (DECIDE_TIMEOUT at most).
     def take_pin(client)
       state = @mutex.synchronize { @state.tap { @state = nil } }
       return nil unless state && state[:slot].is_a?(Integer) && state[:client].equal?(client)
+      return nil unless state[:sent].pop(timeout: DECIDE_TIMEOUT)
 
       state[:thread].alive? ? state[:slot] : nil
     end
 
+    private def skip(slot)
+      Log.info(:model, "warmup_skipped", slot: slot, why: "slot busy")
+      nil
+    end
+
     # Whether a warm-up is running (specs, measurements).
     def running?
       thread = @mutex.synchronize { @thread }

data/lib/samagotchi/question_desk.rb

@@ -180,9 +180,6 @@ module Samagotchi
       true
     end
 
-    # @return [Boolean] the pending question is a standing one
-    def standing? = @lock.synchronize { !@standing.nil? }
-
     private def ask(fields, watch)
       pending = publish(fields)
       id = pending[:id]