samagotchi 0.122.0 → 0.124.0

data/lib/samagotchi/gem_update.rb

@@ -5,6 +5,7 @@ require "net/http"
 require "open3"
 require "rbconfig"
 require "rubygems/package"
+require "time"
 require_relative "version"
 require_relative "redacted_inspect"
 
@@ -22,12 +23,14 @@ module Samagotchi
     end
 
     LATEST_URL = URI("https://rubygems.org/api/v1/versions/samagotchi/latest.json")
+    RELEASES_URL = URI("https://rubygems.org/api/v1/versions/samagotchi.json")
     # Not SAMAGOTCHI_UPDATE_GEM: that is the env form of config update.gem.
     LOCAL_ENV = "SAMAGOTCHI_UPDATE_GEM_FILE"
     TIMEOUT = 5
 
     # source is what `gem install` takes: the gem's name, or a .gem file.
     Latest = Struct.new(:version, :source, keyword_init: true)
+    Release = Data.define(:version, :created_at, :prerelease)
 
     # Runs a command without a shell; [output, success].
     class Runner
@@ -57,7 +60,7 @@ module Samagotchi
       local = @env[LOCAL_ENV].to_s
       return Latest.new(version: Gem::Package.new(local).spec.version.to_s, source: local) unless local.empty?
 
-      version = JSON.parse(@fetcher.call.to_s)["version"].to_s
+      version = JSON.parse(fetch_body(LATEST_URL).to_s)["version"].to_s
       raise Error, "rubygems.org answered without a version" if version.empty? || !Gem::Version.correct?(version)
 
       Latest.new(version: version, source: "samagotchi")
@@ -67,6 +70,29 @@ module Samagotchi
       raise Error, "#{e.class}: #{e.message}".lines.first.strip
     end
 
+    # @return [Array<Release>] rubygems releases, or the one local smoke gem
+    def releases
+      local = @env[LOCAL_ENV].to_s
+      return [local_release(local)] unless local.empty?
+
+      records = JSON.parse(fetch_body(RELEASES_URL).to_s)
+      raise Error, "rubygems.org answered without a releases list" unless records.is_a?(Array)
+
+      records.map do |record|
+        version = record["number"].to_s
+        created_at = record["created_at"].to_s
+        unless Gem::Version.correct?(version) && !created_at.empty? && [true, false].include?(record["prerelease"])
+          raise Error, "rubygems.org answered with an invalid release"
+        end
+
+        Release.new(version: version, created_at: Time.iso8601(created_at), prerelease: record["prerelease"])
+      end
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise Error, "#{e.class}: #{e.message}".lines.first.strip
+    end
+
     def newer?(latest, current = VERSION)
       Gem::Version.new(latest.version) > Gem::Version.new(current)
     end
@@ -83,9 +109,20 @@ module Samagotchi
 
     private
 
-    def fetch
-      Net::HTTP.start(LATEST_URL.host, LATEST_URL.port, use_ssl: true, open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
-        request = Net::HTTP::Get.new(LATEST_URL)
+    def local_release(path)
+      version = Gem::Package.new(path).spec.version
+      Release.new(version: version.to_s, created_at: File.mtime(path), prerelease: version.prerelease?)
+    end
+
+    def fetch_body(url)
+      return @fetcher.call if @fetcher.arity.zero?
+
+      @fetcher.call(url)
+    end
+
+    def fetch(url = LATEST_URL)
+      Net::HTTP.start(url.host, url.port, use_ssl: true, open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
+        request = Net::HTTP::Get.new(url)
         request["User-Agent"] = USER_AGENT
         response = http.request(request)
         raise Error, "rubygems.org answered #{response.code}" unless response.code == "200"

data/lib/samagotchi/guardrail_wiring.rb

@@ -45,8 +45,11 @@ module Samagotchi
     # @param system_one [#call] → SystemOne::Client or nil: the judgment client
     #   (nil while `guardrails.system_one.mode` is off or no host is set)
     # @param cancel_controller [#call] → the running turn's CancellationController, nil
+    # @param participant [#call] (author) → the participant's
+    #   Participants::Entry (participants.json: their name, their grant's
+    #   mode), nil for none
     def initialize(scratch:, hooks:, tools:, session:, model_key:, cancelled:, ask:, model_name: -> {},
-                   notify: ->(_message) {}, system_one: -> {}, cancel_controller: -> {})
+                   notify: ->(_message) {}, system_one: -> {}, cancel_controller: -> {}, participant: ->(_author) {})
       @scratch = scratch
       @hooks_lookup = hooks
       @tools_lookup = tools
@@ -58,6 +61,8 @@ module Samagotchi
       @notify = notify
       @system_one = system_one
       @cancel_controller = cancel_controller
+      @participant = participant
+      @turn_mode = nil
       # Bundle name → the rules last loaded from it whole, kept while the
       # installed version needs a newer chi; [name, version] said so once.
       @loaded_bundle_rules = {}
@@ -96,12 +101,24 @@ module Samagotchi
     end
 
     # A turn starts: its origin (Engine#run_turn's TurnOrigin; nil or a
-    # Hash is read as one, TurnOrigin.of), and the git facts read afresh.
+    # Hash is read as one, TurnOrigin.of), the git facts read afresh, and
+    # a participant's turn's mode decided once for the whole turn
+    # (#turn_mode).
     def begin_turn(origin)
       @origin = TurnOrigin.of(origin)
       @git = Guardrails::GitInfo.new
+      author = turn_author
+      @turn_entry = author && @participant.call(author)
+      @turn_mode = author && ParticipantMode.for_turn(@session_lookup.call, @turn_entry)
     end
 
+    # The running participant turn's mode (ParticipantMode.for_turn: :pair
+    # only in a working session for a participant invited to act), decided
+    # at its start; nil for the owner's turns. The boundary in #checks, the
+    # Engine's stamp and mid-turn stop, and ToolRunner read it.
+    # @return [Symbol, nil]
+    attr_reader :turn_mode
+
     # Who wrote the running turn when it isn't the session's owner (its
     # origin's participant author); nil for the owner's turns and every
     # other origin.
@@ -126,23 +143,34 @@ module Samagotchi
 
     # The gate's core checks, in order. A delegate child's boundary comes
     # before the rules, so its ask keeps the child-boundary rule id (and
-    # its once/session scopes) when a strict rule asks too. The review
-    # boundary comes before both: a participant's review turn is denied
-    # what it may not do, never asked about it.
+    # its once/session scopes) when a strict rule asks too. The
+    # participant's boundary comes before both, by the session's
+    # ParticipantMode: a review turn's (ReviewBoundary) or a pair turn's
+    # (PairBoundary). Either denies what a participant's turn may not do,
+    # never asks about it; both are no-ops for the owner's turns.
     def checks
       rules = self.rules
-      boundary = ParticipantMode.of(@session_lookup.call) == :review ? review_boundary : nil
-      [@failures, boundary, rules.hook_asks, protected_paths,
+      [@failures, participant_boundary, rules.hook_asks, protected_paths,
        (@scratch_writes ||= Guardrails::ScratchWrites.new if @scratch), child_boundary, rules].compact
     end
 
-    # A participant's turn's boundary (Guardrails::ReviewBoundary): in
-    # every session, a no-op unless the running turn's author is a
-    # participant's.
+    # The boundary for a participant's turn in this session (#checks).
+    def participant_boundary
+      @turn_mode == ParticipantMode::PAIR ? pair_boundary : review_boundary
+    end
+
+    # A participant's review turn's boundary (Guardrails::ReviewBoundary): a
+    # no-op unless the running turn's author is a participant's.
     def review_boundary
       @review_boundary ||= Guardrails::ReviewBoundary.new(author: -> { turn_author }, root: -> { boundary_root })
     end
 
+    # A participant's pair turn's boundary (Guardrails::PairBoundary): a
+    # no-op unless the running turn's author is a participant's.
+    def pair_boundary
+      @pair_boundary ||= Guardrails::PairBoundary.new(author: -> { turn_author }, root: -> { boundary_root })
+    end
+
     # The delegate child's boundary (Guardrails::ChildBoundary); nil for
     # any other session.
     def child_boundary
@@ -264,8 +292,12 @@ module Samagotchi
       label = verdict.targets&.label ||
               ToolActivity.plugin_label(acts_as || verdict.call[:name].to_s, registry: @tools_lookup.call)
       # verdict.call is the call that will run (a hook may have replaced it).
+      # A participant's turn's ask names them and offers once only
+      # (Approval.payload's author:), whichever session it is.
+      author = turn_author
       payload = Guardrails::Approval.payload(verdict, label: label, preview: approval_preview(verdict.call),
-                                                      only: (SCRATCH_SCOPES if @scratch))
+                                                      only: (SCRATCH_SCOPES if @scratch), author: author,
+                                                      author_name: (@turn_entry&.name if author))
       # A call on chi's own config, hooks or guardrails is the user's to
       # allow, never a parent agent's (Guardrails::ParentPolicy).
       payload[:user_only] = Guardrails::ParentApprovals.protected_facts?(payload[:approval])
@@ -311,7 +343,8 @@ module Samagotchi
     # System 1's judgment of an ask, written to the log before the user is
     # asked, with the decision it led to: "auto" (it answered for the user),
     # "asked" (on mode, the user decides) or "audit" (audit mode). A
-    # participant's review turn is never judged, and no client (mode off, no
+    # participant's turn (review or pair) is never judged, so never
+    # auto-allowed: its asks go to the owner. No client (mode off, no
     # host) means no line at all. A judgment that fails is logged with p nil,
     # so the failures are in the log too.
     # @return [Hash, nil] {id:, p:, auto:}, nil when nothing was written

data/lib/samagotchi/guardrails/approval.rb

@@ -14,6 +14,16 @@ module Samagotchi
     module Approval
       KIND = "approval"
       HEADER = "Approve tool call?"
+      # A participant's turn's ask (author:): who asks, in the header and as
+      # the question's last line, so a UI that doesn't know the field still
+      # says it.
+      PARTICIPANT_HEADER = "%s's turn asks: approve tool call?"
+      # Who asks, in the plain question (indented) and as the card's line
+      # (approval asked_by:): the one wording every UI shows.
+      ASKED_BY = "asked by: %s's turn (a participant, not you); Allow once only"
+      # The only scope a participant's ask offers: no session, repo or rule
+      # approval is made from a participant's call.
+      PARTICIPANT_SCOPES = %w[once].freeze
       DENY = "Deny"
       ONCE = "Allow once"
 
@@ -28,16 +38,24 @@ module Samagotchi
       #   write: the card shows its diff, the question text one change line
       # @param only [Array<String>, nil] offer no scope beyond these (a
       #   scratch session: once, session); "once" when none is left
+      # @param author [String, nil] a participant's author ("p:<id>") when
+      #   their turn asks: it offers once only (PARTICIPANT_SCOPES), and the
+      #   card names them (approval author:, author_name:, the header)
+      # @param author_name [String, nil] their name (participants.json)
       # @return [Hash] open_question fields; its caller adds user_only:
       #   (ParentApprovals.protected_facts? on approval:, a file that
       #   requires this one)
-      def payload(verdict, label: nil, preview: nil, only: nil)
+      def payload(verdict, label: nil, preview: nil, only: nil, author: nil, author_name: nil)
+        asker = asker(author, author_name)
+        only = PARTICIPANT_SCOPES if asker
         scopes = offered_scopes(verdict, only: only)
         targets = verdict.targets
+        question = question_text(verdict, label: label, preview: preview)
+        question = "#{question}\n  #{format(ASKED_BY, asker)}" if asker
         {
-          question: question_text(verdict, label: label, preview: preview),
+          question: question,
           options: scopes.map { |scope| label(scope, verdict) } + [DENY],
-          header: HEADER,
+          header: asker ? format(PARTICIPANT_HEADER, asker) : HEADER,
           multi_select: false,
           allow_freeform: true,
           effects: effects(scopes),
@@ -63,11 +81,31 @@ module Samagotchi
             source: verdict.source,
             reason: verdict.reason,
             scopes: scopes,
-            preview: preview
+            preview: preview,
+            # A participant's turn asks (nil for the owner's).
+            author: (author.to_s if asker),
+            author_name: (author_name_for(author_name) if asker),
+            asked_by: (format(ASKED_BY, asker) if asker)
           }.compact
         }
       end
 
+      # How a participant's ask names them: their cleaned name, else their
+      # id; nil for the owner's turns.
+      def asker(author, author_name)
+        require_relative "../steer"
+        return nil unless Steer.participant_author?(author)
+
+        name = author_name_for(author_name)
+        name || Steer.participant_id(author.to_s)
+      end
+
+      def author_name_for(author_name)
+        require_relative "../participant_name"
+        name = ParticipantName.clean(author_name)
+        name.empty? ? nil : name
+      end
+
       # Each option's effect for a parent's answer (ParentPolicy): once
       # permits one call, a wider scope more, Deny denies.
       def effects(scopes)

data/lib/samagotchi/guardrails/gate.rb

@@ -85,7 +85,7 @@ module Samagotchi
       # answer that allows it beyond this once is stored.
       def settle_ask(verdict)
         approvals = @approvals_lookup.call
-        if (entry = stored(approvals, verdict))
+        if !verdict.fresh_ask? && (entry = stored(approvals, verdict))
           verdict.settle!(:allow, decided_by: "approval")
           verdict.scope = entry["scope"]
           return verdict

data/lib/samagotchi/guardrails/pair_boundary.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative "review_paths"
+require_relative "shell_paths"
+require_relative "shell_lex"
+require_relative "pair_command"
+require_relative "parent_approvals"
+require_relative "../steer"
+
+module Samagotchi
+  module Guardrails
+    # A participant's pair turn (ParticipantMode :pair, a working session):
+    # it acts with the session's tools under the owner's guardrails, and
+    # their asks go to the owner (GuardrailWiring#request_approval). This
+    # check sits in ReviewBoundary's seat (GuardrailWiring#checks), on in
+    # every guardrails mode and with guardrails.enabled: false, active only
+    # while the running turn's author is a participant. An accident guard
+    # for a trusted team, not containment. It denies, never asks (the
+    # owner's approval would let the participant's text reach what only the
+    # owner should), on:
+    #   - secrets: ReviewPaths' denylist (chi's state and config dirs, the
+    #     web token, grants and every participants.json among them; home
+    #     secret dirs and files: keys, shell startup files, histories,
+    #     credential files; project secret files) on every file tool's path,
+    #     read or written (read, write, edit, a plugin's targets: paths), and
+    #     on what a command does (execute, and any call whose targets carry
+    #     a command: PairCommand, which also refuses chi, background jobs,
+    #     the environment, git settings that run commands and home sweeps);
+    #   - owner-voiced tools (OWNER_VOICED, and any delegate_* tool): what
+    #     speaks or acts in the owner's name beyond this turn (a delegate, a
+    #     reminder, a note to another session, a background task, a
+    #     forgotten output, the session's loaded tools); and memory_write:
+    #     a memory reaches the owner's later sessions;
+    #   - ask_user_question: there is no one on the participant's side to
+    #     answer it here; the model asks in its reply instead.
+    # And it asks the owner, always (Verdict#fresh_ask: no stored approval
+    # answers it, and the rules can't lower it), before a write, an edit or a
+    # command that writes outside the session's project root (the tmp dirs
+    # aside).
+    # Everything else goes on to the owner's checks and rules as for the
+    # owner's turns.
+    class PairBoundary
+      RULE = "pair-boundary"
+      SOURCE = "core"
+      OWNER_VOICED = %w[delegate register_reminder cancel_reminder send_note forget_outputs task_create task_stop
+                        find_tools].freeze
+      OWNER_VOICED_PREFIX = "delegate_"
+      ASK_TOOL = "ask_user_question"
+      WRITE_TOOLS = %w[write edit].freeze
+
+      ADVICE = "This is a participant's turn: work with this session's other tools, and say in your reply what " \
+               "only the owner can do."
+      SECRET = "a participant's turn can't read or write secrets or chi's own files"
+      OWNER_ONLY = "a participant's turn can't use %s: it acts in the owner's name beyond this turn"
+      MEMORY_WRITE = "a participant's turn writes no memories: they reach the owner's later sessions; say in your " \
+                     "reply what to remember"
+      ASK = "a participant's turn can't ask the user: ask in your reply"
+      OUTSIDE_WRITE = "a participant's turn writes outside the session's project"
+      CHI = "a participant's turn can't run chi: its commands act in the owner's name (sessions, shares, answers)"
+      BACKGROUND = "a participant's turn can't leave a command running in the background: it would outlive the turn"
+      ENVIRONMENT = "a participant's turn can't read the environment or the keychain: they hold the owner's secrets"
+      HOME_SWEEP = "a participant's turn can't search or copy a folder that holds secrets or chi's own files"
+      GIT_CONFIG = "a participant's turn can't change git's global config or set what makes git run a command " \
+                   "(core.hooksPath, core.fsmonitor, core.sshCommand, core.pager, core.editor, ! aliases)"
+      UNREADABLE = "a participant's turn runs only commands chi can read: split this command, or write the file " \
+                   "with the write tool"
+      # A pair turn's execute runs without the environment variables whose
+      # names say they hold a secret (Tools::Builtins, PairBoundary.scrubbed_env).
+      SECRET_ENV_NAME = /KEY|TOKEN|SECRET|PASS|CREDENTIAL|AUTH/i
+
+      # The unsets a pair turn's execute adds to its environment: every
+      # variable of +env+ whose name SECRET_ENV_NAME matches.
+      # @return [Hash{String => nil}]
+      def self.scrubbed_env(env = ENV) = env.keys.grep(SECRET_ENV_NAME).to_h { |name| [name, nil] }
+
+      # What a command word that can't be resolved to a path is matched
+      # with: chi's own dirs (ParentApprovals::CHI_TEXT, the state dir,
+      # the web's grants and token), the home secret dirs, and the secret
+      # file names ReviewPaths::SECRET_FILE has.
+      SECRET_TEXT = Regexp.union(
+        ParentApprovals::CHI_TEXT,
+        %r{\.local/state/samagotchi|web-grants|grants\.json|web-token},
+        %r{(?:\A|[\s/'"=])\.(?:ssh|gnupg|aws|kube|docker)(?![\w.-])},
+        %r{(?:\A|[\s/'"=])(?:\.env(?:\.[\w.-]*)?|[._]netrc|\.npmrc|\.pypirc|\.git-credentials)(?![\w-])},
+        /\bid_(?:rsa|dsa|ecdsa|ed25519)\b|credentials|\.(?:pem|p12|pfx|tfstate)\b/
+      )
+
+      # @param author [#call] → String, nil: the running turn's author
+      #   (GuardrailWiring#turn_author); the check is off unless it is a
+      #   participant's (Steer.participant_author?)
+      # @param denied_dirs [#call] → Array<String>: chi's own dirs
+      # @param home [#call] → String, nil
+      # @param root [#call] → String, nil: the session's project root (the
+      #   work tree top of its folder); a write outside it asks the owner
+      #   (none: every write asks)
+      # @param tmp_roots [#call] → Array<String>: where a write neither asks
+      #   nor is denied (PairCommand.tmp_roots)
+      def initialize(author:, root: -> {}, denied_dirs: -> { ReviewPaths.chi_dirs }, home: -> { Dir.home },
+                     tmp_roots: -> { PairCommand.tmp_roots })
+        @author = author
+        @root = root
+        @tmp_roots = tmp_roots
+        @denied_dirs = denied_dirs
+        @home = home
+      end
+
+      # Vote on +verdict+ (its call and targets).
+      def check(verdict)
+        return verdict unless Steer.participant_author?(@author.call)
+
+        if (reason = refusal(verdict))
+          return verdict.deny!(reason, rule: RULE, source: SOURCE, decided_by: "core", advice: ADVICE)
+        end
+
+        if outside_write?(verdict)
+          verdict.ask!(OUTSIDE_WRITE, scopes: %w[once], rule: RULE, source: SOURCE, decided_by: "core")
+          verdict.fresh_ask = true
+        end
+        verdict
+      end
+
+      private
+
+      def refusal(verdict)
+        call = verdict.call || {}
+        tool = call[:name].to_s
+        return ASK if tool == ASK_TOOL
+        return format(OWNER_ONLY, tool) if OWNER_VOICED.include?(tool) || tool.start_with?(OWNER_VOICED_PREFIX)
+        return MEMORY_WRITE if tool == "memory_write"
+
+        targets = verdict.targets
+        return nil unless targets
+
+        paths = denylist
+        return SECRET if paths.secret_refusal(targets.paths.compact)
+        return command(targets, paths).refusal if targets.command
+
+        nil
+      end
+
+      # A write or edit whose path is outside the project root (as given or
+      # as it resolves), or a command that writes there (PairCommand); the
+      # tmp dirs aside.
+      def outside_write?(verdict)
+        targets = verdict.targets
+        return false unless targets
+        return command(targets, nil).outside_writes? if targets.command
+        return false unless WRITE_TOOLS.include?(verdict.call&.dig(:name).to_s)
+
+        paths = targets.paths.to_a.compact
+        root = @root.call.to_s
+        paths.any? do |path|
+          real = ProtectedPaths.real(path)
+          next false if @tmp_roots.call.any? { |tmp| ShellPaths.within?(real, tmp) }
+
+          root.empty? || !ShellPaths.within?(real, ProtectedPaths.real(root))
+        end
+      end
+
+      def command(targets, paths)
+        @command = nil unless @command&.first == targets
+        @command ||= [targets, PairCommand.new(targets.command, cwd: targets.cwd, home: home, root: @root.call,
+                                                                paths: paths || denylist, tmp_roots: @tmp_roots.call)]
+        @command.last
+      end
+
+      def denylist = ReviewPaths.new(root: nil, denied_dirs: @denied_dirs.call, home: @home.call)
+
+      def home = @home.call.to_s
+    end
+  end
+end