reeve 0.0.1 → 0.2.0

data/lib/reeve/context.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "English"
+require "securerandom"
+
+module Reeve
+  # The per-invocation carrier: who is calling, on whose behalf, which tool, with what.
+  #
+  # Created by an adapter or by the caller of the plain interface — never global, never
+  # reused between invocations. The principal is the only mutable field, because the
+  # envelope resolves it after the context exists, and clears it in an +ensure+.
+  class Context
+    UNKNOWN_AGENT_ID = "unknown"
+
+    attr_reader :invocation_id, :tool_name, :arguments, :metadata, :agent, :invoked_at
+    attr_accessor :principal
+
+    def initialize(tool_name:, principal: nil, agent: nil, arguments: nil, metadata: nil,
+                   invoked_at: nil, invocation_id: nil)
+      @tool_name     = validate_tool_name(tool_name)
+      @principal     = principal
+      @agent         = build_agent(agent)
+      @arguments     = symbolize(:arguments, arguments)
+      @metadata      = symbolize(:metadata, metadata)
+      @invoked_at    = invoked_at || Time.now
+      @invocation_id = (invocation_id || SecureRandom.uuid).to_s
+    end
+
+    def principal_resolved?
+      !principal.nil?
+    end
+
+    # Called from the envelope's ensure block: nothing about one invocation may survive
+    # into the next on the same thread (data-model invariant 4).
+    def clear_principal!
+      @principal = nil
+    end
+
+    def principal_type
+      principal&.class&.name
+    end
+
+    def principal_id
+      return nil if principal.nil?
+
+      principal.respond_to?(:id) ? principal.id.to_s : principal.to_s
+    end
+
+    def agent_id
+      agent[:id]
+    end
+
+    def agent_name
+      agent[:name]
+    end
+
+    # The audit-facing projection. The recorder adds the outcome, rule and records;
+    # everything here is known before the tool runs.
+    #
+    # `metadata` belongs here even though nothing in the envelope reads it: the ledger has
+    # a column for it, the recorder maps it, and the contract check requires it — but this
+    # method used to omit it, so the column was written NULL on every call ever made. The
+    # transport detail a reviewer most wants after an incident (which request, which
+    # headers, which client) was accepted at the front door and dropped before the write.
+    def to_h
+      {
+        invocation_id: invocation_id,
+        occurred_at: invoked_at,
+        tool_name: tool_name,
+        agent_id: agent_id,
+        agent_name: agent_name,
+        principal_type: principal_type,
+        principal_id: principal_id,
+        arguments: arguments,
+        metadata: metadata
+      }
+    end
+
+    def inspect
+      "#<Reeve::Context tool=#{tool_name.inspect} principal=#{principal_id.inspect} " \
+        "agent=#{agent_id.inspect} invocation=#{invocation_id.inspect}>"
+    end
+
+    private
+
+    def validate_tool_name(name)
+      string = name&.to_s
+      return string if string && !string.strip.empty?
+
+      raise ArgumentError, "tool_name is required and may not be blank (got #{name.inspect})"
+    end
+
+    def build_agent(agent)
+      attributes = symbolize(:agent, agent)
+      id = attributes[:id]
+      attributes[:id] = id.nil? || id.to_s.strip.empty? ? UNKNOWN_AGENT_ID : id.to_s
+      attributes[:name] = attributes[:name].to_s unless attributes[:name].nil?
+      attributes
+    end
+
+    def symbolize(field, hash)
+      return {} if hash.nil?
+
+      raise ArgumentError, "#{field} must be a Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) do |(key, value), result|
+        result[key.respond_to?(:to_sym) ? key.to_sym : key] = value
+      end
+    end
+  end
+end

data/lib/reeve/decision.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Reeve
+  # The result of a policy evaluation: an outcome, and the rule that produced it.
+  #
+  # A decision without a rule is not a decision — Constitution II requires every ledger
+  # entry to name what decided, so the rule is validated here rather than at write time.
+  # Immutable and comparable by value.
+  class Decision
+    NO_GUARD_DECLARED       = "no_guard_declared"
+    NO_PRINCIPAL            = "no_principal"
+    POLICY_ERROR            = "policy_error"
+    UNKNOWN_RECORD_TYPE     = "unknown_record_type"
+    UNSCOPED_DERIVED_RESULT = "unscoped_derived_result"
+    OUT_OF_SCOPE_RECORD     = "out_of_scope_record"
+    AUDIT_WRITE_FAILED      = "audit_write_failed"
+    # An allowed invocation whose tool body raised. No records reached the agent, so the
+    # ledger records it as a deny — the trace of a call that blew up is the one most
+    # worth having (R5).
+    TOOL_ERROR              = "tool_error"
+
+    # The one reserved *allow* rule: a tool with no guard, permitted because the host
+    # opted into :allow_with_warning. Kept out of RESERVED_RULES, which names deny paths.
+    UNGUARDED_TOOL          = "unguarded_tool"
+
+    # Stable strings. The testing kit and host applications match on them, so a rename
+    # here is a breaking change.
+    RESERVED_RULES = [
+      NO_GUARD_DECLARED,
+      NO_PRINCIPAL,
+      POLICY_ERROR,
+      UNKNOWN_RECORD_TYPE,
+      UNSCOPED_DERIVED_RESULT,
+      OUT_OF_SCOPE_RECORD,
+      AUDIT_WRITE_FAILED,
+      TOOL_ERROR
+    ].freeze
+
+    OUTCOMES = %i[allow deny].freeze
+
+    attr_reader :outcome, :rule, :detail
+
+    def self.allow(rule:, detail: nil)
+      new(outcome: :allow, rule: rule, detail: detail)
+    end
+
+    def self.deny(rule:, detail: nil)
+      new(outcome: :deny, rule: rule, detail: detail)
+    end
+
+    def initialize(outcome:, rule:, detail: nil)
+      @outcome = validate_outcome(outcome)
+      @rule    = validate_rule(rule)
+      @detail  = detail&.to_s
+      freeze
+    end
+
+    def allowed?
+      outcome == :allow
+    end
+
+    def denied?
+      outcome == :deny
+    end
+
+    # True when the rule came from reeve itself rather than from a host policy.
+    def reserved_rule?
+      RESERVED_RULES.include?(rule)
+    end
+
+    def to_h
+      { outcome: outcome.to_s, rule: rule, detail: detail }
+    end
+
+    def ==(other)
+      other.is_a?(Decision) &&
+        other.outcome == outcome &&
+        other.rule == rule &&
+        other.detail == detail
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, outcome, rule, detail].hash
+    end
+
+    def to_s
+      "#{outcome}(#{rule})"
+    end
+
+    def inspect
+      "#<Reeve::Decision #{outcome} rule=#{rule.inspect} detail=#{detail.inspect}>"
+    end
+
+    private
+
+    def validate_outcome(outcome)
+      symbol = outcome.respond_to?(:to_sym) ? outcome.to_sym : outcome
+      return symbol if OUTCOMES.include?(symbol)
+
+      raise ArgumentError, "outcome must be :allow or :deny, got #{outcome.inspect}"
+    end
+
+    def validate_rule(rule)
+      string = rule&.to_s
+      return string.freeze unless string.nil? || string.strip.empty?
+
+      raise ArgumentError, "rule is required and may not be blank (got #{rule.inspect})"
+    end
+  end
+end

data/lib/reeve/errors.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Reeve
+  # Base class for everything reeve raises. Hosts can rescue this one class.
+  class Error < StandardError; end
+
+  # Raised when reeve is asked to run with a configuration it cannot honour.
+  class ConfigurationError < Error; end
+
+  # Raised when a guarded invocation is denied.
+  #
+  # The message names the tool, the principal and the rule, because the first question
+  # a developer asks is "which rule stopped this, and for whom?" (Constitution VI).
+  # It deliberately never names a record: see .out_of_scope.
+  class DeniedError < Error
+    attr_reader :tool_name, :principal_id, :rule, :detail
+
+    def self.from(decision, tool_name:, principal_id:)
+      unless decision.denied?
+        raise ArgumentError, "cannot build a DeniedError from an allow decision (#{decision})"
+      end
+
+      new(
+        tool_name: tool_name,
+        principal_id: principal_id,
+        rule: decision.rule,
+        detail: decision.detail
+      )
+    end
+
+    # FR-006. Fetching a record outside the principal's scope must be indistinguishable
+    # from fetching one that does not exist, so this builder accepts no record at all —
+    # there is nothing to leak, by construction rather than by discipline.
+    def self.out_of_scope(tool_name:, principal_id:)
+      new(
+        tool_name: tool_name,
+        principal_id: principal_id,
+        rule: Decision::OUT_OF_SCOPE_RECORD,
+        detail: "the requested record is not within this principal's scope"
+      )
+    end
+
+    def initialize(tool_name:, principal_id:, rule:, detail: nil)
+      @tool_name    = tool_name&.to_s
+      @principal_id = principal_id&.to_s
+      @rule         = rule.to_s
+      @detail       = detail&.to_s
+      super(build_message)
+    end
+
+    private
+
+    def build_message
+      principal = principal_id.nil? ? "no principal" : "principal #{principal_id}"
+      base = "reeve denied #{tool_name} for #{principal}: #{rule}"
+      detail.nil? ? base : "#{base} (#{detail})"
+    end
+  end
+
+  # Raised when the ledger write fails and audit_failure_mode is :fail (FR-012).
+  #
+  # It carries a rule like any other denial, because the failure is not recorded anywhere
+  # else: the ledger is the thing that failed, so there is no row to read afterwards. The
+  # exception is the only artifact, and a host matching on rules can match on this one.
+  class AuditWriteError < Error
+    attr_reader :invocation_id, :original_error, :rule
+
+    # `during` is whatever the invocation was already raising when the ledger write
+    # failed — usually a DeniedError, sometimes the tool's own exception. It is carried
+    # rather than discarded: the audit failure must win, because a call that cannot be
+    # recorded is a failed call, but the developer still needs to see what the call was
+    # doing at the time.
+    attr_reader :during
+
+    def initialize(invocation_id:, cause: nil, during: nil)
+      @invocation_id  = invocation_id&.to_s
+      @original_error = cause
+      @during         = during
+      @rule           = Decision::AUDIT_WRITE_FAILED
+      message = "reeve could not record invocation #{@invocation_id}"
+      message = "#{message}: #{cause.message}" if cause
+      if during
+        message = "#{message} (while the invocation was already failing with " \
+                  "#{during.class}: #{during.message})"
+      end
+      super(message)
+    end
+  end
+end

data/lib/reeve/fast_mcp.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "../reeve"
+
+begin
+  require "fast_mcp"
+rescue LoadError => e
+  raise Reeve::ConfigurationError,
+        "reeve/fast_mcp needs the fast-mcp gem, which could not be loaded (#{e.message}). " \
+        "Add fast-mcp to your Gemfile, or use Reeve.invoke directly — the core needs no " \
+        "MCP server library."
+end
+
+require_relative "integrations/fast_mcp/context_builder"
+require_relative "integrations/fast_mcp/tool_extension"
+
+module Reeve
+  # Adapters for the MCP server libraries reeve rides on. Each is opt-in, conditionally
+  # loaded, and never a dependency of the core (Constitution IV).
+  module Integrations
+  end
+end
+
+Reeve::Integrations::FastMcp.install!

data/lib/reeve/integrations/fast_mcp/context_builder.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Integrations
+    # The fast-mcp bridge: the DSL on every tool, and the envelope around every call.
+    module FastMcp
+      # Turns what a fast-mcp tool instance knows about its request into the attributes
+      # a Reeve::Context is built from.
+      #
+      # fast-mcp constructs a tool as `tool.new(headers: headers)` per request and calls
+      # `call_with_schema_validation!` on it, so the transport's headers are the only
+      # per-request context a tool has. They are passed through to the principal resolver
+      # untouched: the header that identifies the human is the host's decision, not ours
+      # (research R2, resolved against fast-mcp 1.6.0).
+      module ContextBuilder
+        # Checked in order. The first that answers names the client for attribution only.
+        AGENT_HEADERS = %w[X-MCP-Client X-Client-Name User-Agent].freeze
+
+        module_function
+
+        def attributes(tool)
+          headers = headers_for(tool)
+
+          {
+            agent: { id: agent_id(headers), name: headers["X-MCP-Client"] },
+            metadata: { headers: headers }
+          }
+        end
+
+        def headers_for(tool)
+          headers = tool.respond_to?(:headers) ? tool.headers : nil
+          headers.is_a?(Hash) ? headers : {}
+        end
+
+        # Attribution is not authorization: a client that names itself is recorded by that
+        # name, and one that does not is recorded as unknown rather than refused.
+        def agent_id(headers)
+          AGENT_HEADERS.each do |header|
+            value = headers[header] || headers[header.downcase]
+            return value.to_s unless value.nil? || value.to_s.strip.empty?
+          end
+
+          Context::UNKNOWN_AGENT_ID
+        end
+      end
+    end
+  end
+end

data/lib/reeve/integrations/fast_mcp/tool_extension.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Integrations
+    # The fast-mcp bridge: the DSL on every tool, and the envelope around every call.
+    module FastMcp
+      # Routes every fast-mcp tool call through the envelope.
+      #
+      # Prepended to each tool *subclass* rather than to `FastMcp::Tool` itself: a
+      # prepended module precedes the class's own methods, but a module prepended to the
+      # parent still sits behind the subclass's `call`. Prepending at `inherited` time
+      # works even though `call` is defined afterwards, which is what makes this
+      # impossible to forget — there is no "remember to wrap your tool" step.
+      module ToolExtension
+        def call(**arguments)
+          attributes = ContextBuilder.attributes(self)
+
+          Reeve.invoke(
+            tool: self.class,
+            arguments: arguments,
+            agent: attributes[:agent],
+            metadata: attributes[:metadata]
+          ) { super(**arguments) }
+        end
+      end
+
+      # Installs the extension into every tool defined from here on.
+      module Inheritance
+        def inherited(subclass)
+          super
+          subclass.prepend(ToolExtension)
+        end
+      end
+
+      module_function
+
+      # Idempotent: requiring "reeve/fast_mcp" twice must not stack two envelopes around
+      # the same call.
+      def install!(tool_base = ::FastMcp::Tool)
+        tool_base.include(Reeve::Guard) unless tool_base.include?(Reeve::Guard)
+
+        unless tool_base.singleton_class.include?(Inheritance)
+          tool_base.singleton_class.prepend(Inheritance)
+        end
+
+        # Tools defined before this require still get the envelope.
+        tool_base.subclasses.each do |subclass|
+          subclass.prepend(ToolExtension) unless subclass.include?(ToolExtension)
+        end
+
+        tool_base
+      end
+    end
+  end
+end

data/lib/reeve/invocation.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+module Reeve
+  # The single funnel every guarded tool call passes through:
+  #
+  #   resolve principal → look up guard → authorize → execute → scope → record → return
+  #
+  # One envelope rather than middleware or a patched dispatcher, so there is exactly one
+  # place where "did this get authorized and recorded?" can be answered — and exactly one
+  # place to audit when the answer must be yes.
+  #
+  # Collaborators are injected and default to null objects that fail closed: a kernel with
+  # no authorization module wired in denies everything, and one with no ledger refuses the
+  # call rather than performing it silently.
+  class Invocation
+    # A tool with no guard: there is nothing to consult, so there is nothing to allow.
+    class NullRegistry
+      def guard_for(_tool_name)
+        nil
+      end
+    end
+
+    # No policy adapter wired in: nothing can be evaluated, so nothing is permitted.
+    class NullAuthorizer
+      def authorize(context:, guard:)
+        Decision.deny(rule: Decision::POLICY_ERROR, detail: "no policy adapter is configured")
+      end
+    end
+
+    # No scoper wired in: a result that cannot be narrowed cannot be returned.
+    class NullScoper
+      def scope(context:, guard:, result:)
+        ScopeResult.deny(
+          rule: Decision::UNSCOPED_DERIVED_RESULT,
+          detail: "no scoper is configured, so the result could not be narrowed"
+        )
+      end
+    end
+
+    # Constitution II: a failure to record is a failure of the call. With no ledger
+    # configured there is nothing to fail into, so this refuses rather than no-ops.
+    class NullRecorder
+      def record(_attributes)
+        raise Error, "no audit recorder is configured (run `rails g reeve:install`)"
+      end
+    end
+
+    def self.call(context, **collaborators, &tool)
+      new(context, **collaborators).call(&tool)
+    end
+
+    def initialize(context, registry: nil, authorizer: nil, scoper: nil, recorder: nil,
+                   config: nil)
+      @context    = context
+      @config     = config || Reeve.config
+      @registry   = registry   || NullRegistry.new
+      @authorizer = authorizer || NullAuthorizer.new
+      @scoper     = scoper     || NullScoper.new
+      @recorder   = recorder   || @config.audit_recorder || NullRecorder.new
+    end
+
+    def call(&tool)
+      started = monotonic_now
+      @guard_label = "policy"
+      @scope_result = nil
+
+      @decision = authorize_and_run(&tool)
+      raise denial_error(@decision) if @decision.denied?
+
+      @scope_result.records
+    ensure
+      # Whatever is already on its way out of this method — a tool error or a denial.
+      @in_flight_error = $ERROR_INFO
+      @duration_ms = ((monotonic_now - started) * 1000).round
+      write_entry
+      context.clear_principal!
+    end
+
+    private
+
+    attr_reader :context, :config, :registry, :authorizer, :scoper, :recorder
+
+    def authorize_and_run(&tool)
+      principal = resolve_principal
+      if principal.nil?
+        return Decision.deny(rule: Decision::NO_PRINCIPAL,
+                             detail: principal_denial_detail)
+      end
+
+      context.principal = principal
+
+      guard = look_up_guard
+      return guard if guard.is_a?(Decision) # registry blew up
+
+      if guard.nil?
+        if deny_unguarded?
+          return Decision.deny(rule: Decision::NO_GUARD_DECLARED,
+                               detail: unguarded_detail)
+        end
+
+        return run_unguarded(&tool)
+      end
+
+      decision = authorize(guard)
+      return decision if decision.denied?
+
+      run_guarded(guard, decision, &tool)
+    end
+
+    def resolve_principal
+      resolver = config.principal_resolver
+      return nil if resolver.nil?
+
+      resolver.call(context)
+    rescue StandardError => e
+      # A resolver that raises is a resolver that did not identify anyone (FR-001).
+      @principal_error = e
+      nil
+    end
+
+    def principal_denial_detail
+      return "principal_resolver raised #{@principal_error.class}" if @principal_error
+      return "no principal_resolver is configured" if config.principal_resolver.nil?
+
+      "principal_resolver returned nil"
+    end
+
+    def look_up_guard
+      registry.guard_for(context.tool_name)
+    rescue StandardError => e
+      Decision.deny(rule: Decision::POLICY_ERROR,
+                    detail: "guard lookup raised #{e.class}: #{e.message}")
+    end
+
+    def deny_unguarded?
+      config.unguarded_tools != :allow_with_warning
+    end
+
+    def unguarded_detail
+      "#{context.tool_name} has no guard_with declaration"
+    end
+
+    def authorize(guard)
+      decision = authorizer.authorize(context: context, guard: guard)
+      return decision if decision.is_a?(Decision)
+
+      Decision.deny(
+        rule: Decision::POLICY_ERROR,
+        detail: "authorizer returned #{decision.class}, expected a Reeve::Decision"
+      )
+    rescue StandardError => e
+      Decision.deny(rule: Decision::POLICY_ERROR, detail: "policy raised #{e.class}: #{e.message}")
+    end
+
+    def run_guarded(guard, decision, &tool)
+      result = execute(&tool)
+
+      @scope_result = narrow(guard, result)
+      @scope_result.denied? ? @scope_result.decision : decision
+    end
+
+    # The degraded mode a host opts into while retrofitting guards onto existing tools
+    # (FR-023). The call is unscoped — that is the whole point of the warning.
+    def run_unguarded(&tool)
+      warn_about_unguarded_tool
+      @guard_label = "none"
+      result = execute(&tool)
+      @scope_result = ScopeResult.unscoped(records: result, rule: Decision::UNGUARDED_TOOL)
+      Decision.allow(rule: Decision::UNGUARDED_TOOL, detail: unguarded_detail)
+    end
+
+    def execute(&tool)
+      tool.call
+    rescue StandardError => e
+      # The tool's own failure propagates untouched, but not before the ensure block
+      # records it: the invocations most worth having a trace of are the ones that broke.
+      @decision = Decision.deny(rule: Decision::TOOL_ERROR, detail: "#{e.class}: #{e.message}")
+      @scope_result = ScopeResult.deny(rule: Decision::TOOL_ERROR)
+      raise
+    end
+
+    def narrow(guard, result)
+      scoped = scoper.scope(context: context, guard: guard, result: result)
+      return scoped if scoped.is_a?(ScopeResult)
+
+      ScopeResult.deny(
+        rule: Decision::POLICY_ERROR,
+        detail: "scoper returned #{scoped.class}, expected a Reeve::ScopeResult"
+      )
+    rescue StandardError => e
+      ScopeResult.deny(rule: Decision::POLICY_ERROR,
+                       detail: "scoping raised #{e.class}: #{e.message}")
+    end
+
+    def denial_error(decision)
+      if decision.rule == Decision::OUT_OF_SCOPE_RECORD
+        DeniedError.out_of_scope(tool_name: context.tool_name, principal_id: context.principal_id)
+      else
+        DeniedError.from(decision, tool_name: context.tool_name, principal_id: context.principal_id)
+      end
+    end
+
+    def write_entry
+      return if @entry_written
+
+      @entry_written = true
+      recorder.record(entry_attributes)
+    rescue StandardError => e
+      handle_write_failure(e)
+    end
+
+    def entry_attributes
+      decision = @decision || Decision.deny(rule: Decision::POLICY_ERROR,
+                                            detail: "envelope aborted")
+      scope = @scope_result || ScopeResult.deny(rule: decision.rule, detail: decision.detail)
+
+      context.to_h.merge(scope.to_h).merge(
+        outcome: decision.outcome.to_s,
+        rule: decision.rule,
+        detail: decision.detail,
+        guard: @guard_label,
+        duration_ms: @duration_ms
+      )
+    end
+
+    # Constitution II: a call that cannot be recorded is a failed call, and that holds
+    # whether or not the call was failing already.
+    #
+    # This used to return quietly whenever another exception was in flight, on the
+    # reasoning that the developer needs the original error more than the audit error.
+    # The reasoning was wrong: denials and tool errors are *most* of what a ledger is
+    # consulted about, so the effect was that a broken ledger stayed invisible for exactly
+    # the invocations a compliance review looks for, in the default mode, with no
+    # exception raised. The in-flight error is now carried on the audit error instead of
+    # being traded against it.
+    def handle_write_failure(error)
+      if config.audit_failure_mode == :warn
+        log("reeve could not record invocation #{context.invocation_id}: #{error.message}")
+        return
+      end
+
+      raise AuditWriteError.new(
+        invocation_id: context.invocation_id, cause: error, during: @in_flight_error
+      )
+    end
+
+    def warn_about_unguarded_tool
+      log("reeve: #{context.tool_name} has no guard_with declaration and ran unguarded " \
+          "(unguarded_tools is :allow_with_warning)")
+    end
+
+    def log(message)
+      config.logger&.warn(message)
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end