samagotchi 0.2.0

data/lib/samagotchi/guardrails/approval.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Samagotchi
+  module Guardrails
+    # An ask as a question for the user (Engine#open_question), and the
+    # answer back as a verdict. The question text is plain and complete, so
+    # a UI that doesn't know approvals still shows everything; `approval:`
+    # carries the same facts for UIs that render them richer. Answers map
+    # to scopes by index, never by label.
+    module Approval
+      KIND = "approval"
+      HEADER = "Approve tool call?"
+      DENY = "Deny"
+
+      module_function
+
+      # @param verdict [Verdict] an ask, with its targets and context
+      # @param label [String, nil] a plugin tool's label ("chrome:
+      #   screenshot"): the question names the tool by it, as its row does;
+      #   approval[:tool] stays the raw name
+      # @return [Hash] open_question fields
+      def payload(verdict, label: nil)
+        scopes = offered_scopes(verdict)
+        targets = verdict.targets
+        {
+          question: question_text(verdict, label: label),
+          options: scopes.map { |scope| label(scope, verdict) } + [DENY],
+          header: HEADER,
+          multi_select: false,
+          allow_freeform: true,
+          kind: KIND,
+          approval: {
+            tool: targets&.tool || verdict.call[:name].to_s,
+            label: label,
+            command: targets&.command,
+            paths: targets && !targets.paths.empty? ? targets.paths : nil,
+            cwd: targets&.cwd,
+            repo_root: targets&.repo_root,
+            branch: verdict.context&.branch(targets&.cwd || verdict.context.cwd),
+            rule: verdict.rule,
+            source: verdict.source,
+            reason: verdict.reason,
+            scopes: scopes
+          }.compact
+        }
+      end
+
+      # Settle +verdict+ from open_question's result.
+      # @param answer [Hash, String] {selected_indices:, freeform:} or {error:}
+      # @param scopes [Array<String>] the offered scopes, in option order
+      # @return [Verdict]
+      def settle(verdict, answer, scopes)
+        unless answer.is_a?(Hash) && !answer[:error]
+          return verdict.settle!(:deny, decided_by: "user", note: "The approval was cancelled.")
+        end
+
+        index = Array(answer[:selected_indices]).first
+        if index && index < scopes.size
+          verdict.settle!(:allow, decided_by: "user")
+          verdict.scope = scopes[index]
+          return verdict
+        end
+
+        freeform = answer[:freeform].to_s.strip
+        note = freeform.empty? ? "The user declined this call." : "The user declined this call: #{freeform.inspect}."
+        verdict.settle!(:deny, decided_by: "user", note: note)
+      end
+
+      # The rule's scopes; "rule" only when a rule id names what to approve.
+      def offered_scopes(verdict)
+        verdict.scopes.reject { |scope| scope == "rule" && verdict.rule.nil? }
+      end
+
+      def label(scope, verdict)
+        place = verdict.targets&.repo_root ? "in this repo" : "in this directory"
+        case scope
+        when "once" then "Allow once"
+        when "session" then "Allow this call for the session"
+        when "repo" then "Allow this call #{place}"
+        when "rule" then "Allow rule #{verdict.rule} #{place}"
+        end
+      end
+
+      # How much of a plugin tool's arguments the question shows.
+      ARGS_CHARS = 300
+
+      # A plugin tool's arguments (Targets#args), as the question shows
+      # them and an approval is keyed by, when its targets name no command
+      # or path (an MCP tool): `a=20 b="x y"`, keys sorted, values as JSON.
+      # "" for none (chi's own tools).
+      # @param limit [Integer, nil] cut to this many characters (with …)
+      def args_text(args, limit: nil)
+        return "" unless args.is_a?(Hash) && !args.empty?
+
+        text = args.sort_by { |key, _| key.to_s }.map do |key, value|
+          "#{key}=#{value.is_a?(String) && value.match?(/\A[^\s"=]+\z/) ? value : JSON.generate(value)}"
+        end.join(" ")
+        limit && text.length > limit ? "#{text[0, limit - 1]}…" : text
+      end
+
+      # execute: git push origin main
+      #   in /path/to/repo (repo samagotchi, branch main)
+      #   why: git push publishes commits (rule git-push, bundle guardrails)
+      def question_text(verdict, label: nil)
+        targets = verdict.targets
+        tool = label || targets&.tool || verdict.call[:name].to_s
+        what = targets&.command || (targets && targets.paths.join(", "))
+        what = Approval.args_text(targets&.args, limit: ARGS_CHARS) if what.to_s.empty?
+        lines = ["#{tool}: #{what}"]
+        if targets
+          repo = targets.repo_root
+          branch = verdict.context&.branch(targets.cwd)
+          where = repo ? "repo #{File.basename(repo)}#{", branch #{branch}" if branch}" : "not in a repo"
+          lines << "  in #{targets.cwd} (#{where})"
+        end
+        who = verdict.rule ? ["rule #{verdict.rule}", verdict.source].compact.join(", ") : (verdict.source || "hook")
+        reason = verdict.reason.to_s.strip
+        lines << "  why: #{reason.empty? ? "(no reason given)" : reason} (#{who})"
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/approvals.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "time"
+require_relative "../log"
+require_relative "approval"
+
+module Samagotchi
+  module Guardrails
+    # The user's stored approvals: one JSON file under the state dir,
+    # written aside and renamed under an exclusive flock (several chi
+    # processes share it). An entry relaxes an ask, never a deny:
+    #   session — this exact call (tool + normalized command / paths) in
+    #             this session;
+    #   repo    — this exact call in this repo (the cwd outside a repo);
+    #   rule    — anything this rule (from this source) asks about here.
+    # "once" is never stored. A file that doesn't parse is moved aside to
+    # approvals.json.corrupt-<UTC time>[-N], with a warning, and the store
+    # starts empty: it only means more asks, and nothing is overwritten.
+    class Approvals
+      FILE = "approvals.json"
+      STORED_SCOPES = %w[session repo rule].freeze
+
+      # @param sessions_dir [String] Session's state dir
+      #   ($XDG_STATE_HOME/samagotchi/sessions): the store sits beside it,
+      #   not among the sessions
+      def self.dir_for(sessions_dir) = File.join(File.dirname(sessions_dir), "guardrails")
+
+      attr_reader :path
+
+      def initialize(dir:, warn: ->(msg) { Log.warn(:guardrails, "approvals_unreadable", echo: msg) })
+        @dir = dir
+        @path = File.join(dir, FILE)
+        @warn = warn
+        @warned = false
+      end
+
+      # @return [Array<Hash>] the entries (string keys), oldest first
+      def entries
+        read
+      end
+
+      # @param verdict [Verdict] an ask with its targets and context
+      # @return [Hash, nil] the first entry that allows it
+      def match(verdict)
+        key = self.class.key_for(verdict)
+        place = self.class.place_for(verdict)
+        session_id = verdict.context&.session_id
+        read.find do |e|
+          case e["scope"]
+          when "session" then session_id && e["session_id"] == session_id && e["key"] == key
+          when "repo" then e["repo_root"] == place && e["key"] == key
+          when "rule" then verdict.rule && e["rule"] == verdict.rule && e["source"] == verdict.source &&
+                           e["repo_root"] == place
+          end
+        end
+      end
+
+      # Store the verdict's allowed scope (not "once").
+      # @return [Hash, nil] the entry
+      def add(verdict, scope)
+        return nil unless STORED_SCOPES.include?(scope)
+
+        entry = { "scope" => scope, "tool" => verdict.targets&.tool || verdict.call[:name].to_s,
+                  "rule" => verdict.rule, "source" => verdict.source, "created_at" => Time.now.utc.iso8601 }
+        case scope
+        when "session" then entry.merge!("session_id" => verdict.context&.session_id, "key" => self.class.key_for(verdict))
+        when "repo" then entry.merge!("repo_root" => self.class.place_for(verdict), "key" => self.class.key_for(verdict))
+        when "rule" then entry["repo_root"] = self.class.place_for(verdict)
+        end
+        entry.compact!
+        update { |list| list << entry unless list.any? { |e| e.except("created_at") == entry.except("created_at") } }
+        entry
+      end
+
+      # Remove entry +index+ (0-based, as #entries lists them).
+      # @return [Hash, nil] the removed entry
+      def revoke(index)
+        removed = nil
+        update { |list| removed = list.delete_at(index) if index >= 0 && index < list.size }
+        removed
+      end
+
+      # tool + the normalized command, or the sorted paths; for a plugin
+      # tool with neither (an MCP tool), its arguments, so "this call" is
+      # this call.
+      def self.key_for(verdict)
+        t = verdict.targets
+        return "#{verdict.call[:name]}:" unless t
+        return "#{t.tool}:#{t.command.to_s.strip.gsub(/\s+/, " ")}" if t.command
+        return "#{t.tool}:#{Approval.args_text(t.args)}" if t.paths.empty?
+
+        "#{t.tool}:#{t.paths.sort.join("\n")}"
+      end
+
+      def self.place_for(verdict)
+        t = verdict.targets
+        t&.repo_root || t&.cwd || verdict.context&.cwd
+      end
+
+      private
+
+      # @param locked [Boolean] the caller holds the store's lock
+      def read(locked: false)
+        return [] unless File.exist?(@path)
+
+        parse(File.read(@path))
+      rescue JSON::ParserError, SystemCallError => e
+        aside = begin
+          locked ? set_aside : with_lock { set_aside }
+        rescue SystemCallError
+          nil
+        end
+        return read(locked: locked) if aside == :readable
+
+        unless @warned
+          @warned = true
+          where = aside ? "moved it to #{aside}" : "left it in place"
+          @warn.call("[samagotchi:guardrails] #{@path} is unreadable (#{e.message}); #{where}, no stored approvals apply")
+        end
+        []
+      end
+
+      def parse(text)
+        data = JSON.parse(text)
+        raise JSON::ParserError, "not a list" unless data.is_a?(Array)
+
+        data.select { |e| e.is_a?(Hash) }
+      end
+
+      # Under the lock: rename the file aside if it is still unreadable.
+      # @return [String, :readable] where it went; :readable when another
+      #   process replaced or removed it meanwhile
+      def set_aside
+        return :readable unless File.exist?(@path)
+
+        begin
+          parse(File.read(@path))
+          return :readable
+        rescue JSON::ParserError, SystemCallError
+          nil
+        end
+        base = "#{@path}.corrupt-#{Time.now.utc.strftime("%Y%m%dT%H%M%SZ")}"
+        # A second one within the same second must not replace the first
+        # (we hold the lock, so nobody else takes the name meanwhile).
+        aside = base
+        n = 1
+        aside = "#{base}-#{n += 1}" while File.exist?(aside)
+        File.rename(@path, aside)
+        aside
+      end
+
+      def with_lock
+        FileUtils.mkdir_p(@dir)
+        File.open(File.join(@dir, "approvals.lock"), File::RDWR | File::CREAT, 0o600) do |lock|
+          lock.flock(File::LOCK_EX)
+          yield
+        end
+      end
+
+      def update
+        with_lock do
+          list = read(locked: true)
+          yield list
+          tmp = "#{@path}.#{Process.pid}.#{Thread.current.object_id}.tmp"
+          begin
+            File.write(tmp, JSON.pretty_generate(list))
+            File.rename(tmp, @path)
+          ensure
+            FileUtils.rm_f(tmp)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/context.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Samagotchi
+  module Guardrails
+    # Where a tool call runs and on whose behalf: the process cwd, the
+    # session, the host (interface) and who queued the turn (origin). Repo
+    # root and branch come from git, asked once per directory per turn.
+    class Context
+      # :repl — the plain REPL answers on the turn thread;
+      # :worker — a shared-session worker (attached TUI / web answer);
+      # :non_interactive — nobody can answer (-p --non-interactive, specs).
+      INTERFACES = %i[repl worker non_interactive].freeze
+
+      attr_reader :cwd, :session_id, :interface, :origin
+
+      def initialize(cwd: Dir.pwd, session_id: nil, interface: :non_interactive, origin: nil, git: GitInfo.new)
+        @cwd = cwd
+        @session_id = session_id
+        @interface = interface
+        @origin = origin
+        @git = git
+      end
+
+      def repo_root(dir = @cwd) = @git.root(dir)
+      def branch(dir = @cwd) = @git.branch(dir)
+
+      # The hook event's context: hash.
+      def to_h
+        { cwd: @cwd, repo_root: repo_root, branch: branch, session_id: @session_id,
+          interface: @interface, origin: @origin }
+      end
+    end
+
+    # `git rev-parse` per directory, memoized (one GitInfo per turn).
+    class GitInfo
+      def initialize
+        @cache = {}
+        @mutex = Mutex.new
+      end
+
+      def root(dir) = info(dir)[:root]
+      def branch(dir) = info(dir)[:branch]
+
+      private
+
+      def info(dir)
+        dir = File.expand_path(dir.to_s)
+        @mutex.synchronize { @cache[dir] ||= probe(dir) }
+      end
+
+      def probe(dir)
+        return {} unless File.directory?(dir)
+
+        out, status = Open3.capture2e("git", "-C", dir, "rev-parse", "--show-toplevel", "--abbrev-ref", "HEAD")
+        lines = out.lines.map(&:strip)
+        # A repo with no commits yet has no HEAD: only the root answers.
+        unless status.success?
+          out, status = Open3.capture2e("git", "-C", dir, "rev-parse", "--show-toplevel")
+          return {} unless status.success?
+
+          lines = [out.strip]
+        end
+        { root: lines[0], branch: lines[1] }
+      rescue SystemCallError
+        {}
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/gate.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "verdict"
+require_relative "context"
+require_relative "targets"
+require_relative "approvals"
+require_relative "protected_paths"
+require_relative "../log"
+
+module Samagotchi
+  module Guardrails
+    # Decides whether a tool call may run. The voters are before_tool_call
+    # hooks: through event[:guardrail] (#deny!, #ask!) or the legacy flag
+    # (event[:blocked] = true, optional event[:block_reason]). The flag is
+    # folded into the verdict after each hook, so a later hook can't undo a
+    # 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)
+      # @param approver [#call, nil] settles an ask (Engine#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: -> {}, 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
+        @approver = approver
+        @approvals_lookup = approvals_lookup
+        @checks_lookup = checks_lookup
+        @cancelled_lookup = cancelled_lookup
+        @tools_lookup = tools_lookup
+      end
+
+      # @param call [Hash] the parsed tool call
+      # @param iteration [Integer]
+      # @param params [String] the call's one-line preview
+      # @return [Verdict]
+      def evaluate(call, iteration:, params:)
+        context = @context_lookup.call
+        verdict = Verdict.new(call: call)
+        if @cancelled_lookup.call
+          verdict.deny!("the turn was stopped", decided_by: "core")
+          verdict.context = context
+          verdict.targets = targets_for(call, context)
+          return verdict
+        end
+        before = { type: :before_tool_call, iteration: iteration, call: call.dup, params: params,
+                   blocked: false, block_reason: nil, guardrail: verdict,
+                   context: context.to_h, targets: targets_for(call, 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
+      end
+
+      # Settle an ask: the approver asks the user; with none, or one that
+      # fails, it is denied.
+      # @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)
+        approvals = @approvals_lookup.call
+        if (entry = stored(approvals, verdict))
+          verdict.settle!(:allow, decided_by: "approval")
+          verdict.scope = entry["scope"]
+          return verdict
+        end
+        return verdict.settle!(:deny, decided_by: "no one", note: "No one to approve it.") unless @approver
+
+        @approver.call(verdict)
+        return verdict.settle!(:deny, decided_by: "no one", note: "No one to approve it.") if verdict.ask?
+
+        remember(approvals, verdict)
+        verdict
+      rescue StandardError => e
+        verdict.settle!(:deny, decided_by: "core", note: "The approval failed (#{e.class}: #{e.message}).")
+      end
+
+      private
+
+      def stored(approvals, verdict)
+        approvals&.match(verdict)
+      rescue StandardError
+        nil
+      end
+
+      # A store that can't be written only means the next call asks again.
+      def remember(approvals, verdict)
+        return unless approvals && verdict.allow? && verdict.scope
+
+        approvals.add(verdict, verdict.scope)
+      rescue StandardError => e
+        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, registry: @tools_lookup.call)
+      end
+
+      # Registry#fire_each rescues a raising hook itself.
+      def fire_each(name, event, &after_each)
+        @hooks_lookup.call&.fire_each(name, event, &after_each)
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/load_failures.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Guardrails
+    # What failed to load at Engine start: hooks, bundle hook checksums,
+    # rule files. A required one makes the gate deny every tool call (a
+    # guardrail that silently vanished is the failure this guards against);
+    # the rest are only announced.
+    class LoadFailures
+      Failure = Struct.new(:what, :reason, :required, keyword_init: true)
+
+      def initialize
+        @list = []
+        @mutex = Mutex.new
+      end
+
+      # @param what [String] e.g. "hook guard.rb (config)"
+      def add(what, reason, required:)
+        @mutex.synchronize { @list << Failure.new(what: what, reason: reason, required: required) }
+      end
+
+      def list = @mutex.synchronize { @list.dup }
+      def any? = !list.empty?
+      def required = list.select(&:required)
+
+      # A core check: deny every call while a required guardrail is missing.
+      def check(verdict)
+        first = required.first
+        return verdict unless first
+
+        verdict.deny!("required guardrail #{first.what} failed to load: #{first.reason}",
+                      rule: "guardrail-load", source: "core", decided_by: "core")
+      end
+
+      # One line for the UIs, or nil.
+      def message
+        items = list
+        return nil if items.empty?
+
+        text = items.map { |f| "#{f.what} failed to load (#{f.reason})" }.join("; ")
+        text += ". Every tool call is denied until it is fixed" if items.any?(&:required)
+        text
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/protected_paths.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Guardrails
+    # Core checks on what the file tools (write, edit, memory_write) touch,
+    # after the hooks and before the rules. Paths are compared with
+    # symlinks resolved (on the longest existing parent).
+    #   deny: the approval store's dir and installed bundles (.bundles/:
+    #         hooks, rules, manifests); nothing legitimate writes there
+    #         through the file tools.
+    #   ask (once / session): config.yml and the plain hooks dir. The
+    #         system bundle's config protocol edits config.yml with
+    #         write/edit, so this keeps the user in the loop without
+    #         breaking it.
+    # execute can still write all of them (the guardrails bundle adds a
+    # text match for that).
+    class ProtectedPaths
+      FILE_TOOLS = %w[write edit memory_write].freeze
+      SOURCE = "core"
+
+      # @param store_dir [String] <state dir>/guardrails
+      # @param bundles_dir [String] <memories>/.bundles
+      # @param config_path [String] config.yml
+      # @param hooks_dir [String] the plain hooks dir
+      def initialize(store_dir:, bundles_dir:, config_path:, hooks_dir:)
+        @deny = [
+          ["guardrail-store", store_dir, "the approval store belongs to the user"],
+          ["installed-bundles", bundles_dir, "installed bundles (hooks, rules, manifests) are changed by chi bundle install"]
+        ]
+        @ask = [
+          ["chi-config", config_path, "changes chi's config.yml"],
+          ["chi-hooks", hooks_dir, "changes chi's hooks"]
+        ]
+      end
+
+      # Vote on +verdict+ (its targets).
+      def check(verdict)
+        targets = verdict.targets
+        return verdict unless targets && FILE_TOOLS.include?(targets.tool)
+
+        paths = targets.paths.map { |p| self.class.real(p) }
+        @deny.each do |rule, root, reason|
+          next unless paths.any? { |p| self.class.within?(p, root) }
+
+          verdict.deny!(reason, rule: rule, source: SOURCE, decided_by: "core")
+        end
+        @ask.each do |rule, root, reason|
+          next unless paths.any? { |p| self.class.within?(p, root) }
+
+          verdict.ask!(reason, scopes: %w[once session], rule: rule, source: SOURCE, decided_by: "core")
+        end
+        verdict
+      end
+
+      # +path+ with symlinks resolved on its longest existing parent.
+      def self.real(path)
+        path = File.expand_path(path)
+        rest = []
+        current = path
+        until File.exist?(current) || current == File.dirname(current)
+          rest.unshift(File.basename(current))
+          current = File.dirname(current)
+        end
+        File.join(File.realpath(current), *rest)
+      rescue SystemCallError
+        path
+      end
+
+      def self.within?(path, root)
+        return false if root.nil? || root.to_s.empty?
+
+        root = real(root.to_s.chomp("/"))
+        path == root || path.start_with?(File.join(root, ""))
+      end
+    end
+  end
+end