samagotchi 0.31.0 → 0.32.0

data/lib/samagotchi/context_note.rb

@@ -11,16 +11,22 @@ module Samagotchi
     KIND = "note"
     # The message keys a note carries besides role and content; everything
     # that copies messages field by field must keep them.
-    KEYS = %i[kind note_id source from_session from_cwd].freeze
+    # context_source: the attached context source a note is about
+    # (ContextAbsorber), so the UIs can tie it to its chip.
+    KEYS = %i[kind note_id source from_session from_cwd context_source].freeze
 
     module_function
 
-    # Takes SessionInbox.read_note's keys.
+    # Takes SessionInbox.read_note's keys. +turn_start+ / +turn_id+: the
+    # note starts a turn chi runs for it (a context wake), as a wake turn's
+    # delegate report does (Steer.turn_prompt?).
     # @return [Hash] the conversation message
-    def message(note_id:, text:, source:, created_at: nil, from_session: nil, from_cwd: nil, **)
+    def message(note_id:, text:, source:, created_at: nil, from_session: nil, from_cwd: nil, context_source: nil,
+                turn_start: nil, turn_id: nil, **)
       { role: "system", kind: KIND, note_id: note_id, source: source, from_session: from_session,
-        from_cwd: from_cwd, content: frame(text, source: source, created_at: created_at,
-                                                 from_session: from_session, from_cwd: from_cwd) }.compact
+        from_cwd: from_cwd, context_source: context_source, turn_start: (true if turn_start == true), turn_id: turn_id,
+        content: frame(text, source: source, created_at: created_at, from_session: from_session,
+                             from_cwd: from_cwd) }.compact
     end
 
     def frame(text, source:, created_at: nil, from_session: nil, from_cwd: nil)

data/lib/samagotchi/context_poller.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "context_fetch"
+require_relative "context_sources"
+require_relative "log"
+
+module Samagotchi
+  # A session worker's thread that keeps its attached context fresh: every
+  # TICK_SECONDS it runs each command source (the session's and its
+  # project's, not muted here) whose last try is older than its interval
+  # (--every, else context.every_seconds), and calls +on_change+ after a
+  # new text or a failure so the loop absorbs it at once. The first pass,
+  # right after the worker starts, runs every source not tried in the last
+  # MIN_EVERY_SECONDS: a woken worker's first absorb says what changed while
+  # it was away.
+  #
+  # Polling isn't activity: it never holds the worker up (WorkerIdleExit),
+  # and it stops with it (#stop kills a running command's group). Project
+  # sources are shared by the project's workers; ContextFetch's lock and a
+  # second freshness check under it make one fetch per interval.
+  class ContextPoller
+    TICK_SECONDS = 5
+
+    # @param project_root [String, nil] Session#project_root
+    # @param cwd [String] the session's folder (a session source runs there)
+    # @param on_change [#call] after a fetch brought a new text or failed
+    def initialize(session_id:, state_dir:, project_root:, cwd:, on_change:, tick: TICK_SECONDS)
+      @session_id = session_id
+      @state_dir = state_dir
+      @project_root = project_root
+      @cwd = cwd
+      @on_change = on_change
+      @tick = tick
+      @own = ContextSources.session_location(session_id, state_dir: state_dir)
+      @queue = Thread::Queue.new
+      @stopping = false
+    end
+
+    def start
+      @thread ||= Thread.new do
+        Thread.current.name = "context-poller"
+        run
+      end
+      self
+    end
+
+    # Stops the loop and kills a command it is running; returns once it has.
+    def stop
+      @stopping = true
+      @queue << :stop
+      @thread&.join((ContextFetch::KILL_GRACE_SECONDS * 3) + @tick)
+      @thread = nil
+    end
+
+    # One pass (the thread's loop body; specs call it).
+    # @param first [Boolean] the worker's first pass
+    def poll(first: false)
+      ContextSources.attached(@session_id, project_root: @project_root, state_dir: @state_dir).each do |attached|
+        break if @stopping
+        next if attached.source.push? || @own.muted?(attached.name)
+
+        interval = first ? ContextSources::MIN_EVERY_SECONDS : interval_of(attached.source)
+        age = attached.snapshot.age
+        next if age && age < interval
+
+        outcome = ContextFetch.fetch(attached, cwd: cwd_for(attached), fresh_within: interval, cancelled: -> { @stopping })
+        @on_change.call if %i[new error].include?(outcome.status)
+      rescue StandardError => e
+        Log.exception(:context, "poll_failed", e, name: attached.name)
+      end
+    end
+
+    private
+
+    def run
+      first = true
+      until @stopping
+        poll(first: first)
+        first = false
+        @queue.pop(timeout: @tick)
+      end
+    rescue StandardError => e
+      Log.exception(:context, "poller_crashed", e)
+    end
+
+    def interval_of(source)
+      seconds = source.every_seconds || Config.get("context.every_seconds").to_i
+      [seconds, ContextSources::MIN_EVERY_SECONDS].max
+    end
+
+    # A session's source runs in the session's folder, a project's in the
+    # project root (the session's folder when the root is no checkout).
+    def cwd_for(attached)
+      return @cwd if attached.location.session?
+
+      ContextSources.project_cwd(@project_root, @cwd)
+    end
+  end
+end

data/lib/samagotchi/context_providers.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "shellwords"
+
+module Samagotchi
+  autoload :ContextSources, File.expand_path("context_sources", __dir__)
+  autoload :Log, File.expand_path("log", __dir__)
+  module MemoryBundle
+    autoload :Provenance, File.expand_path("memory_bundle/provenance", __dir__)
+  end
+
+  # Declarative context providers (attached context, §3.9): a bundle's
+  # manifest maps a URL pattern to a source, so any process (the CLI, the
+  # web server, a worker) can attach a URL without loading plugins:
+  #
+  #   context_providers:
+  #     - match: '\Ahttps://github\.com/([^/]+)/([^/]+)/pull/(\d+)'
+  #       name: 'pr-\3'
+  #       cmd: '{ruby} {bundle_dir}/scripts/pr_context.rb {url}'
+  #       why: 'GitHub PR'
+  #       every_seconds: 300
+  #
+  # The installer records them in the bundle's provenance; .resolve reads
+  # them from there. +name+ takes the match's groups (\1…); +cmd+ takes
+  # {url}, the matched URL (shell-quoted), when the source is attached, and
+  # keeps {bundle_dir}, the installed bundle's folder, and {ruby}, the Ruby
+  # chi runs on, for ContextFetch to fill in when it runs: a bundle upgrade
+  # moves nothing, and a `ruby` on the PATH may be another one (macOS's 2.6,
+  # a launchd PATH).
+  module ContextProviders
+    # A provider as the manifest declares it.
+    Provider = Data.define(:match, :name, :cmd, :why, :every_seconds) do
+      def to_h = { "match" => match, "name" => name, "cmd" => cmd, "why" => why, "every_seconds" => every_seconds }.compact
+
+      def regexp = Regexp.new(match)
+    end
+
+    # What a URL resolved to: the provider's bundle, and the source's
+    # fields (+cmd+ still holding {bundle_dir}).
+    Resolved = Data.define(:bundle, :name, :cmd, :why, :hint, :every_seconds)
+
+    class Invalid < ArgumentError; end
+
+    BUNDLE_DIR = "{bundle_dir}"
+    RUBY = "{ruby}"
+    URL = "{url}"
+    MIN_EVERY_SECONDS = 30
+
+    module_function
+
+    # The manifest's context_providers: list.
+    # @return [Array<Provider>] [] when absent
+    # @raise [Invalid]
+    def parse_list(raw)
+      return [] if raw.nil?
+      raise Invalid, "context_providers: must be a list of mappings" unless raw.is_a?(Array)
+
+      raw.map { |item| parse(item) }
+    end
+
+    # @raise [Invalid]
+    def parse(item)
+      raise Invalid, "context_providers: each item must be a mapping, not #{item.inspect}" unless item.is_a?(Hash)
+
+      data = item.transform_keys(&:to_s)
+      %w[match name cmd].each do |key|
+        value = data[key]
+        raise Invalid, "context_providers: an item has no #{key}:" unless value.is_a?(String) && !value.strip.empty?
+      end
+      begin
+        Regexp.new(data["match"])
+      rescue RegexpError => e
+        raise Invalid, "context_providers: match #{data["match"].inspect} isn't a regular expression (#{e.message})"
+      end
+      Provider.new(match: data["match"], name: data["name"], cmd: data["cmd"], why: data["why"]&.to_s,
+                   every_seconds: every(data["every_seconds"]))
+    end
+
+    # The source the installed bundles' providers make of +url+: the first
+    # bundle (by name) whose provider matches. A bundle whose providers
+    # don't parse is skipped (logged).
+    # @return [Resolved, nil] nil when none matches
+    # @raise [Invalid] the provider makes a name that isn't a source name
+    def resolve(url)
+      url = url.to_s.strip
+      MemoryBundle::Provenance.each_installed do |bundle, data|
+        next if data[:error] || !data[:context_providers].is_a?(Array)
+
+        providers(bundle, data).each do |provider|
+          match = provider.regexp.match(url) or next
+          return resolved(bundle, provider, match)
+        end
+      end
+      nil
+    end
+
+    # Whether an installed bundle declares a provider (the web's "+ URL").
+    def any?
+      MemoryBundle::Provenance.each_installed.any? do |_bundle, data|
+        !data[:error] && data[:context_providers].is_a?(Array) && !data[:context_providers].empty?
+      end
+    end
+
+    def providers(bundle, data)
+      parse_list(data[:context_providers])
+    rescue Invalid => e
+      Log.warn(:context, "providers_unreadable", bundle: bundle, msg: e.message)
+      []
+    end
+
+    def resolved(bundle, provider, match)
+      url = match[0]
+      name = provider.name.gsub(/\\(\d)/) { match[Regexp.last_match(1).to_i].to_s }
+      begin
+        ContextSources.check_name!(name)
+      rescue ContextSources::Invalid
+        raise Invalid, "bundle #{bundle} makes #{name.inspect} of it, which isn't a source name"
+      end
+      Resolved.new(bundle: bundle, name: name, cmd: provider.cmd.gsub(URL) { Shellwords.escape(url) },
+                   why: provider.why, hint: url, every_seconds: provider.every_seconds)
+    end
+
+    # +source+'s command as it runs: {bundle_dir} is its provider's
+    # installed folder, once that bundle is there and its scripts are as
+    # installed (they run outside the guardrails gate, as a plugin loads:
+    # checked the same way).
+    # @return [String]
+    # @raise [Invalid] the bundle is gone or a script changed
+    def command_for(source)
+      return source.cmd unless source.provider
+
+      provenance = MemoryBundle::Provenance.new(name: source.provider)
+      data = provenance.read
+      raise Invalid, "bundle #{source.provider} isn't installed" unless data
+
+      scripts = data[:scripts].is_a?(Hash) ? data[:scripts] : {}
+      scripts.each do |file, meta|
+        path = File.join(provenance.scripts_dir, file.to_s)
+        recorded = MemoryBundle::Provenance.recorded_sha(meta.is_a?(Hash) ? meta[:sha256] : nil)
+        next if File.file?(path) && MemoryBundle::Provenance.file_sha(path) == recorded
+
+        raise Invalid, "bundle #{source.provider}'s scripts/#{file} differs from the installed one (reinstall the bundle)"
+      end
+      source.cmd.gsub(BUNDLE_DIR) { Shellwords.escape(provenance.bundle_dir) }.gsub(RUBY) { Shellwords.escape(RbConfig.ruby) }
+    end
+
+    def every(value)
+      return nil if value.nil?
+
+      seconds = Integer(value.to_s, 10, exception: false)
+      unless seconds && seconds >= MIN_EVERY_SECONDS
+        raise Invalid, "context_providers: every_seconds is #{value.inspect}; it takes seconds, at least #{MIN_EVERY_SECONDS}"
+      end
+
+      seconds
+    end
+  end
+end