samagotchi 0.154.1 → 0.155.0

data/lib/samagotchi/guardrail_wiring.rb

@@ -24,8 +24,17 @@ module Samagotchi
   # a tool call is judged in, the approval question, and the Gate the kernel
   # asks before every tool call.
   #
-  # What it needs from the Engine comes through lookups, read at call time.
+  # What it needs from the Engine comes through lookups, read at call time;
+  # what it needs of a turn (its author, participant mode, git facts,
+  # origin) comes with the turn's TurnContext, which the Gate is given per
+  # call. It keeps no per-turn state.
   class GuardrailWiring
+    # What #begin_turn decides for a turn, once (Engine#begin_turn puts it
+    # in the TurnContext): its Guardrails::GitInfo (asked afresh), the
+    # participant's Participants::Entry and their turn's mode (nil both for
+    # the owner's turns).
+    TurnStart = Data.define(:git, :participant, :mode)
+
     # @return [Guardrails::LoadFailures] what failed to load (hooks, rules)
     attr_reader :failures
 
@@ -33,11 +42,10 @@ module Samagotchi
     attr_reader :approvals
 
     # @param scratch   [Boolean] a `chi scratch` session (writes into the memories are denied)
-    # @param hooks     [#call] → Hooks::Registry
-    # @param tools     [#call] → Tools::Registry
+    # @param tools     [#call] → Tools::Registry: an approval's plugin label.
+    #   A lookup: the Engine builds its wiring (and so the load failures its
+    #   hooks are loaded into, ExtensionLoad) before its tools and hooks.
     # @param session   [#call] → Session, nil
-    # @param model_key [#call] → String, the effective model's overlay key
-    # @param model_name [#call] → String, nil: the effective model's bare name
     # @param cancelled [#call] → Boolean, whether the running turn is cancelled
     # @param ask       [#call] (fields) → the answer; the Engine's question flow
     # @param notify    [#call] (message) → shows a guardrails line in every UI
@@ -50,15 +58,11 @@ module Samagotchi
     # @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: -> {}, system_one_runs: -> {}, cancel_controller: -> {},
-                   participant: ->(_author) {})
+    def initialize(scratch:, tools:, session:, cancelled:, ask:, notify: ->(_message) {}, system_one: -> {},
+                   system_one_runs: -> {}, cancel_controller: -> {}, participant: ->(_author) {})
       @scratch = scratch
-      @hooks_lookup = hooks
       @tools_lookup = tools
       @session_lookup = session
-      @model_key_lookup = model_key
-      @model_name_lookup = model_name
       @cancelled_lookup = cancelled
       @ask = ask
       @notify = notify
@@ -66,15 +70,12 @@ module Samagotchi
       @system_one_runs = system_one_runs
       @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 = {}
       @kept_noticed = {}
       @failures = Guardrails::LoadFailures.new
       @rules_mutex = Mutex.new
-      @git = Guardrails::GitInfo.new
-      @origin = TurnOrigin::NONE
     end
 
     # Who can answer an approval: :worker or :non_interactive (the
@@ -104,53 +105,44 @@ module Samagotchi
       @protected = nil
     end
 
-    # A turn starts: its origin (Engine#run_turn's TurnOrigin; nil or a
-    # 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 && participant_turn_mode(@session_lookup.call, @turn_entry)
+    # A turn starts (Engine#begin_turn, before it is published): the git
+    # facts read afresh, and a participant's turn's mode decided once for
+    # the whole turn from its origin (Engine#run_turn's TurnOrigin; nil or a
+    # Hash is read as one, TurnOrigin.of). Nothing is kept here.
+    # @param session [Session, nil] the turn's
+    # @return [TurnStart]
+    def begin_turn(origin, session:)
+      author = TurnOrigin.of(origin).participant_author
+      entry = author && @participant.call(author)
+      TurnStart.new(git: Guardrails::GitInfo.new, participant: entry,
+                    mode: author && participant_turn_mode(session, entry))
     end
 
     # A participant's turn's mode: in a Verify fresh child the one saved
     # on it at spawn (VerifyFreshOrigin#turn_mode: :review unless saved
-    # :pair), never looked up again; elsewhere ParticipantMode.for_turn.
+    # :pair), never looked up again; elsewhere ParticipantMode.for_turn
+    # (:pair only in a working session for a participant invited to act).
     def participant_turn_mode(session, entry)
       fresh = session.respond_to?(:verify_fresh) && session.verify_fresh
       fresh ? fresh.turn_mode : ParticipantMode.for_turn(session, entry)
     end
     private :participant_turn_mode
 
-    # 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.
-    # @return [String, nil]
-    def turn_author = @origin.participant_author
-
-    # The gate every tool call asks first.
+    # The gate every tool call asks first, given the call's TurnContext
+    # (Guardrails::Gate#evaluate's context:): its judged context (#context),
+    # its checks (#checks) and its approval (#request_approval) are that
+    # turn's.
+    # @param hooks [Hooks::Registry, nil] the voters (the Engine's)
+    # @param tools [Tools::Registry, nil] the session's tools (the Engine's)
     # @return [Guardrails::Gate]
-    def gate
+    def gate(hooks:, tools:)
       Guardrails::Gate.new(
-        -> { @hooks_lookup.call },
-        context_lookup: -> { context },
-        model_key_lookup: -> { @model_key_lookup.call },
-        model_name_lookup: -> { @model_name_lookup.call },
-        approver: ->(verdict) { request_approval(verdict) },
+        hooks: hooks,
+        tools: tools,
+        context_for: ->(turn) { context(turn) },
+        approver: ->(verdict, turn) { request_approval(verdict, turn) },
         approvals_lookup: -> { @approvals },
-        checks_lookup: -> { checks },
-        cancelled_lookup: -> { @cancelled_lookup.call },
-        tools_lookup: -> { @tools_lookup.call }
+        checks_for: ->(turn) { checks(turn) }
       )
     end
 
@@ -161,39 +153,42 @@ module Samagotchi
     # 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
+    # @param turn [TurnContext] the call's turn
+    def checks(turn)
       rules = self.rules
-      [@failures, participant_boundary, rules.hook_asks, protected_paths,
-       (@scratch_writes ||= Guardrails::ScratchWrites.new if @scratch), child_boundary, rules].compact
+      [@failures, participant_boundary(turn), rules.hook_asks, protected_paths,
+       (@scratch_writes ||= Guardrails::ScratchWrites.new if @scratch), child_boundary(turn), rules].compact
     end
 
-    # The boundary for a participant's turn in this session (#checks).
-    def participant_boundary
-      @turn_mode == ParticipantMode::PAIR ? pair_boundary : review_boundary
+    # The boundary for a participant's turn in this session (#checks), by
+    # the turn's mode.
+    def participant_boundary(turn)
+      turn.participant_mode == ParticipantMode::PAIR ? pair_boundary(turn) : review_boundary(turn)
     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 })
+    # no-op unless +turn+'s author is a participant's.
+    def review_boundary(turn)
+      Guardrails::ReviewBoundary.new(author: -> { turn.author }, root: -> { boundary_root(turn.git) })
     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 })
+    # no-op unless +turn+'s author is a participant's.
+    def pair_boundary(turn)
+      Guardrails::PairBoundary.new(author: -> { turn.author }, root: -> { boundary_root(turn.git) })
     end
 
-    # The delegate child's boundary (Guardrails::ChildBoundary); nil for
-    # any other session.
-    def child_boundary
+    # The delegate child's boundary (Guardrails::ChildBoundary), on +turn+'s
+    # git facts; nil for any other session.
+    def child_boundary(turn)
       return nil unless @session_lookup.call&.delegate?
 
-      @child_boundary ||= Guardrails::ChildBoundary.new(
-        root: -> { boundary_root },
-        worktrees: -> { (root = boundary_root) ? @git.worktrees(root) : [] },
-        common_dir: -> { (root = boundary_root) && @git.common_dir(root) },
-        branch: -> { (root = boundary_root) && @git.branch(root) }
+      git = turn.git
+      Guardrails::ChildBoundary.new(
+        root: -> { boundary_root(git) },
+        worktrees: -> { (root = boundary_root(git)) ? git.worktrees(root) : [] },
+        common_dir: -> { (root = boundary_root(git)) && git.common_dir(root) },
+        branch: -> { (root = boundary_root(git)) && git.branch(root) }
       )
     end
 
@@ -285,11 +280,13 @@ module Samagotchi
       end
     end
 
-    # The context the gate sees for a tool call now.
+    # The context the gate sees for a tool call of +turn+ now: the process
+    # cwd, the session, the interface, the turn's origin and git facts.
+    # @param turn [TurnContext]
     # @return [Guardrails::Context]
-    def context
+    def context(turn)
       Guardrails::Context.new(cwd: Dir.pwd, session_id: @session_lookup.call&.id, interface: interface,
-                              origin: @origin.wire, git: @git)
+                              origin: turn.origin.wire, git: turn.git)
     end
 
     # Ask the user to approve a call the gate voted `ask` on, through the
@@ -297,8 +294,10 @@ module Samagotchi
     # verdict: allow with the picked scope, or deny with a note for the
     # model. A --non-interactive run has no one to ask and denies at once.
     # @param verdict [Guardrails::Verdict]
+    # @param turn [TurnContext, nil] the call's turn (its author, the
+    #   participant's name); nil: the owner's
     # @return [Guardrails::Verdict]
-    def request_approval(verdict)
+    def request_approval(verdict, turn = nil)
       if interface == :non_interactive
         return verdict.settle!(:deny, decided_by: "no one", note: "No one to approve it (non-interactive run).")
       end
@@ -313,10 +312,10 @@ module Samagotchi
       # 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
+      author = turn&.author
       payload = Guardrails::Approval.payload(verdict, label: label, preview: approval_preview(verdict.call),
                                                       only: (SCRATCH_SCOPES if @scratch), author: author,
-                                                      author_name: (@turn_entry&.name if author))
+                                                      author_name: (turn.participant&.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])
@@ -324,8 +323,8 @@ module Samagotchi
       # one that passes every gate is allowed once without reaching them
       # (docs/guardrails.md, "System 1").
       judgment = begin
-        system_one_judge(payload, targets: verdict.targets, ask_user: verdict.fresh_ask? || verdict.second_rule_ask?,
-                         other_rules: verdict.other_ask_rules)
+        system_one_judge(payload, author: author, targets: verdict.targets,
+                                  ask_user: verdict.fresh_ask? || verdict.second_rule_ask?, other_rules: verdict.other_ask_rules)
       rescue LLM::RequestCancelled
         return turn_stopped(verdict)
       end
@@ -370,9 +369,10 @@ module Samagotchi
     # so the failures are in the log too.
     # With +ask_user+ (a fresh ask, a second rule's) it is judged and logged, never answered.
     # +other_rules+ are the ids of the other rules asking about the same call.
+    # +author+ is the turn's (TurnContext#author).
     # @return [Hash, nil] {id:, p:, auto:}, nil when nothing was written
-    def system_one_judge(payload, targets: nil, ask_user: false, other_rules: nil)
-      return nil if Steer.participant_author?(turn_author)
+    def system_one_judge(payload, author: nil, targets: nil, ask_user: false, other_rules: nil)
+      return nil if Steer.participant_author?(author)
 
       client = @system_one.call
       log = system_one_log
@@ -513,13 +513,14 @@ module Samagotchi
     end
 
     # The work tree top of the session's working_directory (the folder
-    # itself outside a repo, or when it's gone); never Dir.pwd, which is
-    # the waker's cwd for a worker whose folder is gone.
-    def boundary_root
+    # itself outside a repo, or when it's gone), asked of +git+ (the turn's
+    # GitInfo); never Dir.pwd, which is the waker's cwd for a worker whose
+    # folder is gone.
+    def boundary_root(git)
       dir = @session_lookup.call&.working_directory.to_s
       return nil if dir.empty?
 
-      @git.root(dir) || File.expand_path(dir)
+      git.root(dir) || File.expand_path(dir)
     end
 
     # The rules of a bundle that needs a newer chi: the ones last loaded

data/lib/samagotchi/guardrails/gate.rb

@@ -16,65 +16,65 @@ module Samagotchi
     # deny. A hook may replace event[:call]; the verdict carries the final
     # call.
     class Gate
-      # @param hooks_lookup [#call] returns the Hooks::Registry (or nil);
-      #   read per call, since the Engine sets the kernel's hooks after
-      #   the kernel is built.
-      # @param context_lookup [#call] returns the Context for this call
-      #   (the Engine's: session, interface, origin, per-turn git cache)
-      # @param model_key_lookup [#call] the model key (memory overlays, rules' models:)
-      # @param model_name_lookup [#call] the bare model name (rules' models:)
-      # @param approver [#call, nil] settles an ask (Engine#request_approval);
-      #   without one an ask is denied
+      # What a call is judged in comes with it: #evaluate's +context:+, the
+      # call's turn (TurnContext: its controller, model key and name, and
+      # what +context_for+ and +checks_for+ make of it).
+      #
+      # @param hooks [Hooks::Registry, nil] the before_tool_call voters (the
+      #   Engine's registry, built before its gate; nil: no hooks)
+      # @param context_for [#call] (turn) → the Context for a call of that
+      #   turn (the Engine's: session, interface, origin, the turn's git cache)
+      # @param approver [#call, nil] (verdict, turn) settles an ask
+      #   (GuardrailWiring#request_approval); without one an ask is denied
       # @param approvals_lookup [#call] returns the Approvals store (or nil)
-      # @param checks_lookup [#call] core checks (#check(verdict)) run on the
-      #   final call after the hooks: protected paths, then the rules
-      # @param cancelled_lookup [#call] true once the turn was cancelled (a
-      #   hook's stop_turn): the rest of a batch is denied without a vote
-      # @param tools_lookup [#call] returns the Tools::Registry (or nil): a
-      #   plugin tool's targets: say what its call acts on
-      def initialize(hooks_lookup, context_lookup: -> { Context.new }, model_key_lookup: -> {}, model_name_lookup: -> {},
-                     approver: nil, approvals_lookup: -> {}, checks_lookup: -> { [] }, cancelled_lookup: -> { false },
-                     tools_lookup: -> {})
-        @hooks_lookup = hooks_lookup
-        @context_lookup = context_lookup
-        @model_key_lookup = model_key_lookup
-        @model_name_lookup = model_name_lookup
+      # @param checks_for [#call] (turn) → core checks (#check(verdict)) run
+      #   on the final call after the hooks: protected paths, then the rules
+      # @param tools [Tools::Registry, nil] the session's tools (the Engine's,
+      #   built before its gate): a plugin tool's targets: say what its call
+      #   acts on
+      def initialize(hooks: nil, tools: nil, context_for: ->(_turn) { Context.new }, approver: nil, approvals_lookup: -> {},
+                     checks_for: ->(_turn) { [] })
+        @hooks = hooks
+        @context_for = context_for
         @approver = approver
         @approvals_lookup = approvals_lookup
-        @checks_lookup = checks_lookup
-        @cancelled_lookup = cancelled_lookup
-        @tools_lookup = tools_lookup
+        @checks_for = checks_for
+        @tools = tools
       end
 
       # @param call [Hash] the parsed tool call
+      # @param context [TurnContext] the call's turn: a cancelled one's
+      #   controller denies the call without a vote (a hook's stop_turn: the
+      #   rest of a batch); its model key and name go to the targets
+      #   (memory overlays, rules' models:)
       # @param iteration [Integer]
       # @param params [String] the call's one-line preview
       # @param verdict [Verdict, nil] the one the voters vote on (the test
       #   kit's recording one, maybe with a vote already in); default a new
       #   one for +call+
       # @return [Verdict]
-      def evaluate(call, iteration:, params:, verdict: nil)
-        context = @context_lookup.call
+      def evaluate(call, context:, iteration:, params:, verdict: nil)
+        judged = @context_for.call(context)
         verdict ||= Verdict.new(call: call)
         verdict.call = call
-        if @cancelled_lookup.call
+        if context.cancelled?
           verdict.deny!("the turn was stopped", decided_by: "core")
-          verdict.context = context
-          verdict.targets = targets_for(call, context)
+          verdict.context = judged
+          verdict.targets = targets_for(call, judged, context)
           return verdict
         end
         before = { type: :before_tool_call, iteration: iteration, call: call.dup, params: params,
                    blocked: verdict.deny?, block_reason: (verdict.reason if verdict.deny?), guardrail: verdict,
-                   context: context.to_h, targets: targets_for(call, context).to_h }
+                   context: judged.to_h, targets: targets_for(call, judged, context).to_h }
         fire_each(:before_tool_call, before) do |event|
           verdict.legacy_deny!(event[:block_reason]) if event[:blocked]
           event[:blocked] = verdict.deny?
           event[:block_reason] = verdict.reason if verdict.deny?
         end
         verdict.call = before[:call] || call
-        verdict.context = context
-        verdict.targets = targets_for(verdict.call, context)
-        Array(@checks_lookup.call).each { |check| check.check(verdict) }
+        verdict.context = judged
+        verdict.targets = targets_for(verdict.call, judged, context)
+        Array(@checks_for.call(context)).each { |check| check.check(verdict) }
         verdict
       end
 
@@ -83,7 +83,8 @@ module Samagotchi
       # @return [Verdict]
       # A stored approval that covers the call allows it without asking; an
       # answer that allows it beyond this once is stored.
-      def settle_ask(verdict)
+      # @param context [TurnContext] the call's turn (the approver's)
+      def settle_ask(verdict, context:)
         approvals = @approvals_lookup.call
         if !verdict.fresh_ask? && (entry = stored(approvals, verdict))
           verdict.settle!(:allow, decided_by: "approval")
@@ -92,7 +93,7 @@ module Samagotchi
         end
         return verdict.settle!(:deny, decided_by: "no one", note: "No one to approve it.") unless @approver
 
-        @approver.call(verdict)
+        @approver.call(verdict, context)
         return verdict.settle!(:deny, decided_by: "no one", note: "No one to approve it.") if verdict.ask?
 
         remember(approvals, verdict)
@@ -118,14 +119,14 @@ module Samagotchi
         Log.warn(:guardrails, "approval_store_failed", echo: "[samagotchi:guardrails] could not store the approval: #{e.class}: #{e.message}", error: e.class.name)
       end
 
-      def targets_for(call, context)
-        Targets.for(call, context, model_key: @model_key_lookup.call, model_name: @model_name_lookup.call,
-                                   registry: @tools_lookup.call)
+      def targets_for(call, judged, turn)
+        Targets.for(call, judged, model_key: turn.model_key, model_name: turn.model_name, registry: @tools,
+                                  surface: turn.surface)
       end
 
       # Registry#fire_each rescues a raising hook itself.
       def fire_each(name, event, &)
-        @hooks_lookup.call&.fire_each(name, event, &)
+        @hooks&.fire_each(name, event, &)
       end
     end
   end

data/lib/samagotchi/guardrails/pair_boundary.rb

@@ -146,7 +146,8 @@ module Samagotchi
       )
 
       # @param author [#call] → String, nil: the running turn's author
-      #   (GuardrailWiring#turn_author); the check is off unless it is a
+      #   (the call's TurnContext#author, GuardrailWiring#review_boundary /
+      #   #pair_boundary); 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

data/lib/samagotchi/guardrails/review_boundary.rb

@@ -45,7 +45,8 @@ module Samagotchi
       MEMORY_SCOPE = "a participant's review turn reads project memories only: call memory_read with scope: project"
 
       # @param author [#call] → String, nil: the running turn's author
-      #   (GuardrailWiring#turn_author); the check is off unless it is a
+      #   (the call's TurnContext#author, GuardrailWiring#review_boundary /
+      #   #pair_boundary); the check is off unless it is a
       #   participant's (Steer.participant_author?)
       # @param root [#call] → String, nil: the session's project root (the
       #   work tree top of its folder); nil denies every read

data/lib/samagotchi/guardrails/targets.rb

@@ -113,7 +113,9 @@ module Samagotchi
       # @param model_name [String, nil] the bare model name, for a rule's models:
       # @param registry [Tools::Registry, nil] the session's tools: a plugin
       #   tool's entry says what it acts on (its targets:)
-      def self.for(call, context, model_key: nil, model_name: nil, registry: nil)
+      # @param surface [Tools::ToolSurface, nil] the turn's: call_tool's
+      #   targets name what the turn reaches (nil: the Registry now)
+      def self.for(call, context, model_key: nil, model_name: nil, registry: nil, surface: nil)
         tool = call[:name].to_s
         base = context.cwd
         command = nil
@@ -136,7 +138,7 @@ module Samagotchi
         when "memory_write"
           paths << memory_path(call, model_key)
         else
-          given = plugin_targets(call, registry)
+          given = plugin_targets(call, registry, surface)
           command = given[:command]
           given_cwd = given[:cwd].to_s.strip
           cwd = File.expand_path(given_cwd, base) unless given_cwd.empty?
@@ -163,12 +165,12 @@ module Samagotchi
       # logged) when it names a core tool or another bundle's tool, so a
       # call can't pass for one and match (or reuse the approvals of) its
       # rules. label: counts when it is one short line (.label_of).
-      def self.plugin_targets(call, registry)
+      def self.plugin_targets(call, registry, surface = nil)
         entry = registry && registry[call[:name].to_s]
         none = { command: nil, paths: [], cwd: nil, acts_as: nil, args: nil, label: nil }
         return none unless entry && !entry.core? && entry.targets
 
-        given = entry.targets.call(call)
+        given = entry.targets_of(call, surface)
         return none unless given.is_a?(Hash)
 
         given = given.transform_keys(&:to_sym)

data/lib/samagotchi/guardrails_command.rb

@@ -166,7 +166,7 @@ module Samagotchi
     # The rule set as a worker would load it now, the rule's id looked up in
     # it. Every other answer than ASKS names what stands in the way.
     def rule_status(id)
-      wiring = GuardrailWiring.new(scratch: false, hooks: -> {}, tools: -> {}, session: -> {}, model_key: -> {},
+      wiring = GuardrailWiring.new(scratch: false, tools: -> {}, session: -> {},
                                    cancelled: -> { false }, ask: ->(_fields) {})
       rules = wiring.rules
       failed = wiring.failures.required