agentadmit 1.12.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35cfc75d6a091ef7f5940c488c472efad1c6d48a68c670e6c5e1522dbe9abb06
-  data.tar.gz: 0a9c2ecbc1fcdab6255e709519625cc1dbc9944d36d2b9725d5069a44544b222
+  metadata.gz: 3d3b45175d51202f94a44cfda45acd2eedbd6e96453686633e2c23fe1e9e4b07
+  data.tar.gz: 8e6e17f6848db25e36996afcb1e16ed45ec0ab591647cdc9bbd56f51b1b1957d
 SHA512:
-  metadata.gz: 39bb513f8747187ffeb5d7bb73f4557c47a9da0a95f1bd8b56130f95b38406081befb47570f425afbdfbc1ca322069459c5ebf3e4fcb1f4c164320242c306882
-  data.tar.gz: 35577380cb5d5e783fe05e68c67c291238de414dd9b8fb99cb4d9ea8f75a5befed74c501ccd50e1a2eade6ffe3dc3d009d712ef5f44f1b1ba41e7928d8c20a99
+  metadata.gz: e77aed424389ce8a3c15445505cf32cadad2f04a004d4eb003b06c07891556c1968dda9c27506045ea7762c054f31b26c5c7271b79c96fc696423edee7655a6f
+  data.tar.gz: 4526e4389bc7dad6a0799d0633082f9c885afff37c4aaa80be55065856d82a507bf12d20270e27cb636a057342995e880aeaa5734edfbfe8bd67e2110cb61223

data/README.md

@@ -449,6 +449,77 @@ result = AgentAdmit::IntrospectionClient.new.verify(
 
 The local `ScopeEnforcement` checks (`require_scope!`, `require_scope_if_agent!`) are unchanged -- defense in depth on top of the hosted decision.
 
+### Outcome reporting
+
+Successful verify responses may include `result.audit_row_id`, the hosted
+audit row id for that call. After your handler runs, you can append what your
+app observed:
+
+```ruby
+client = AgentAdmit::IntrospectionClient.new
+result = client.verify(token, scope_used: "write:payments",
+                       endpoint: request.path, method: request.request_method)
+
+begin
+  # run the app action
+  client.report_outcome(result.audit_row_id,
+                        outcome: "executed",
+                        status_class: "2xx") if result.audit_row_id
+rescue
+  client.report_outcome(result.audit_row_id,
+                        outcome: "failed",
+                        status_class: "5xx") if result.audit_row_id
+  raise
+end
+```
+
+`outcome` must be `"executed"`, `"failed"`, or `"unknown"`. `unknown` is
+only for an explicit "we cannot truthfully classify this" case; it is never
+chosen automatically. `status_class` may be `"1xx"` through `"5xx"` or `nil`.
+Outcome rows report what the app observed after verification; they are not
+independent proof of execution.
+
+Rack middleware can do the common status mapping for you:
+
+```ruby
+use AgentAdmit::Middleware,
+    scope_for: "write:payments",
+    action_summary: ->(env) { "Pay Alex $50" },
+    report_outcome: true
+```
+
+With `report_outcome: true`, the middleware reports only after the downstream
+Rack app returns a response triple and the status has an observable class.
+Statuses below 400 report `"executed"`; statuses 400 and above report
+`"failed"`. If the app raises, aborts before returning a triple, returns no
+observable status, or verify did not include `audit_row_id`, the middleware
+does not guess. Reporting errors are logged and never replace the app's
+response.
+
+For downstream code, the Rack env includes `env["agentadmit.audit_row_id"]`
+when the hosted service returned one.
+
+### Replay receipts
+
+When an agent retries with an already-consumed confirm-each-time attestation,
+verify may return `result.consumed_receipt`. It is a diagnostic receipt for
+the earlier consumption event:
+
+```ruby
+result.consumed_receipt
+# => {
+#      "consumed_at" => "2026-09-30T02:54:07.000Z",
+#      "connection_id" => "conn_123",
+#      "chain_seq" => nil,
+#      "row_hash" => nil
+#    }
+```
+
+This is not a fresh authorization and must not be treated as permission to
+run the action. It exists so agents and apps can explain an
+`already_consumed` replay without staging another confirmation. Rack exposes
+the typed block at `env["agentadmit.consumed_receipt"]` when present.
+
 ### Active-error responses are denials
 
 An introspection response with `active: true` AND a string `error` field means the token itself is valid but the authorization service refused this call. The SDK treats every such response as a denial, never a pass-through -- the downstream app does not run:

data/lib/agentadmit/introspection_client.rb

@@ -27,11 +27,14 @@ module AgentAdmit
     ATTESTATION_MAX = 120
     DIGEST_MAX      = 128
     SUMMARY_MAX     = 200
+    OUTCOMES        = %w[executed failed unknown].freeze
+    STATUS_CLASSES  = %w[1xx 2xx 3xx 4xx 5xx].freeze
 
     IntrospectionResult = Struct.new(:user_id, :connection_id, :scopes, :agent_label,
                                      :sub, :role, :app_id, :jti, :exp, :consent,
                                      :presence, :purpose, :user_intent,
-                                     :action_confirmation, keyword_init: true) do
+                                     :action_confirmation, :audit_row_id,
+                                     :consumed_receipt, keyword_init: true) do
       def has_scope?(scope)
         scopes.include?(scope)
       end
@@ -83,9 +86,30 @@ module AgentAdmit
       def action_confirmed?
         action_confirmation.is_a?(Hash) && action_confirmation["consumed"] == true
       end
+
+      # `audit_row_id` (String or nil) identifies the hosted audit row for
+      # this successful verify call. Use it with #report_outcome after the
+      # application observes whether its handler executed or failed.
+
+      # `consumed_receipt` (Hash or nil) is a replay diagnostic for an
+      # already-consumed confirm-each-time attestation. It is not a fresh
+      # authorization and must not be treated as permission to run.
     end
 
     class << self
+      def status_class_for(status)
+        code = Integer(status) rescue nil
+        return nil unless code && (100..599).cover?(code)
+
+        "#{code / 100}xx"
+      end
+
+      def outcome_for_status(status)
+        status_class_for(status) ? (Integer(status) < 400 ? "executed" : "failed") : nil
+      rescue ArgumentError, TypeError
+        nil
+      end
+
       ##
       # `sha256:<hex>` over the RAW request body bytes, so a confirmation
       # covers the exact payload and not merely the route. nil for an empty
@@ -151,6 +175,23 @@ module AgentAdmit
           "summary"           => nullable.call(raw["summary"]) }
       end
 
+      ##
+      # A strictly-typed replay diagnostic for an already-consumed action
+      # attestation, or nil when the block is absent/malformed. This is a
+      # receipt for an earlier consumption event, not authorization for this
+      # call.
+      #
+      def parse_consumed_receipt(raw)
+        return nil unless raw.is_a?(Hash)
+        return nil unless raw["consumed_at"].is_a?(String)
+        return nil unless raw["connection_id"].is_a?(String)
+
+        { "consumed_at"   => raw["consumed_at"],
+          "connection_id" => raw["connection_id"],
+          "chain_seq"     => raw["chain_seq"].is_a?(Integer) ? raw["chain_seq"] : nil,
+          "row_hash"      => raw["row_hash"].is_a?(String) ? raw["row_hash"] : nil }
+      end
+
       ##
       # The agent's X-AgentAdmit-Action-Attestation header from a Rack env:
       # first value only, trimmed, capped at 120 characters. nil when absent
@@ -363,6 +404,10 @@ module AgentAdmit
               "consumed" => true }
           end
 
+        audit_row_id = data["audit_row_id"]
+        audit_row_id = nil unless audit_row_id.is_a?(String)
+        consumed_receipt = self.class.parse_consumed_receipt(data["consumed_receipt"])
+
         return IntrospectionResult.new(
           user_id:      data["user_id"],
           connection_id: data["connection_id"],
@@ -377,7 +422,9 @@ module AgentAdmit
           presence:     presence,
           purpose:      purpose,
           user_intent:  user_intent,
-          action_confirmation: action_confirmation
+          action_confirmation: action_confirmation,
+          audit_row_id: audit_row_id,
+          consumed_receipt: consumed_receipt
         )
       end
 
@@ -385,6 +432,60 @@ module AgentAdmit
       raise IntrospectionError, "Unexpected exit from retry loop"
     end
 
+    ##
+    # Report what the application observed after a successful verify call.
+    #
+    # This appends an outcome row to the hosted tamper-evident audit chain.
+    # It reports the app's observed result; it is not independent proof of
+    # execution. Use outcome: "unknown" only when you explicitly cannot
+    # classify the result.
+    #
+    # @param audit_row_id [String] result.audit_row_id from #verify
+    # @param outcome [String] "executed" | "failed" | "unknown"
+    # @param status_class [String, nil] "1xx".."5xx" or nil
+    # @return [Hash] parsed hosted outcome response
+    # @raise [ArgumentError] invalid arguments
+    # @raise [IntrospectionError] hosted service unreachable or rejected the report
+    #
+    def report_outcome(audit_row_id, outcome:, status_class: nil)
+      unless audit_row_id.is_a?(String) && !audit_row_id.empty?
+        raise ArgumentError, "audit_row_id is required"
+      end
+      unless OUTCOMES.include?(outcome)
+        raise ArgumentError, "outcome must be executed, failed, or unknown"
+      end
+      unless status_class.nil? || STATUS_CLASSES.include?(status_class)
+        raise ArgumentError, "status_class must be 1xx, 2xx, 3xx, 4xx, 5xx, or nil"
+      end
+
+      origin = @config.api_url.sub(%r{/\z}, "")
+      uri = URI.parse("#{origin}/api/v1/audit/#{audit_row_id}/outcome")
+      http = build_http(uri)
+
+      request = Net::HTTP::Post.new(uri.path)
+      request["Authorization"] = "Bearer #{@config.api_key}"
+      request["Content-Type"]  = "application/json"
+      request.body = JSON.generate(outcome: outcome, status_class: status_class)
+
+      response = begin
+        http.request(request)
+      rescue StandardError => e
+        raise IntrospectionError, "Outcome report failed: #{e.message}"
+      end
+
+      unless (200..299).cover?(response.code.to_i)
+        data = JSON.parse(response.body) rescue {}
+        raise IntrospectionError,
+              data["error_description"] || data["error"] || "Outcome report returned #{response.code}"
+      end
+
+      begin
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise IntrospectionError, "Outcome report response is not valid JSON"
+      end
+    end
+
     CALLER_CLASSES = %w[human_session in_app_ai external_agent].freeze
 
     ##

data/lib/agentadmit/middleware.rb

@@ -12,6 +12,10 @@ module AgentAdmit
   #   env['agentadmit.connection_id'] -- connection identifier
   #   env['agentadmit.agent_label']   -- agent display name
   #   env['agentadmit.presence']      -- human-presence block (Hash) or nil
+  #   env['agentadmit.audit_row_id']  -- hosted audit row id for this verify
+  #   env['agentadmit.consumed_receipt']
+  #                                   -- replay diagnostic for an already-
+  #                                      consumed confirmation, or nil
   #   env['agentadmit.action_confirmation']
   #                                   -- {"action_session_id" =>, "consumed" => true}
   #                                      when a confirm-each-time confirmation
@@ -66,16 +70,25 @@ module AgentAdmit
     #   request-body digest for this middleware. AgentAdmit does not verify
     #   the summary against the request; it proves what the human was shown.
     #
-    def initialize(app, scope_for: nil, action_summary: nil, &action_summary_block)
+    # @param report_outcome [Boolean] when true, reports the downstream
+    #   Rack response status class to AgentAdmit after the app returns a
+    #   response triple. Reporting is skipped when the app raises, returns no
+    #   observable Rack triple, or has no audit_row_id. Reporting failures are
+    #   logged and never replace the app's response.
+    #
+    def initialize(app, scope_for: nil, action_summary: nil, report_outcome: false,
+                   &action_summary_block)
       @app = app
       @client = IntrospectionClient.new
       @config = AgentAdmit.configuration || Config.new
       @scope_for = scope_for
       @action_summary = action_summary || action_summary_block
+      @report_outcome = report_outcome
     end
 
     def call(env)
       auth = env["HTTP_AUTHORIZATION"] || ""
+      result = nil
 
       if BEARER_AGENT_RE.match?(auth)
         # Strip the scheme prefix (case-insensitively) to get the bare token.
@@ -96,6 +109,8 @@ module AgentAdmit
           env["agentadmit.connection_id"] = result.connection_id
           env["agentadmit.agent_label"] = result.agent_label
           env["agentadmit.presence"] = result.presence
+          env["agentadmit.audit_row_id"] = result.audit_row_id
+          env["agentadmit.consumed_receipt"] = result.consumed_receipt if result.consumed_receipt
           # Only set when the hosted service actually SPENT a confirmation on
           # this call; the key stays absent otherwise, so `env.key?` is a
           # truthful test.
@@ -116,7 +131,9 @@ module AgentAdmit
         end
       end
 
-      @app.call(env)
+      response = @app.call(env)
+      report_outcome_after_response(result, response) if @report_outcome && result
+      response
     end
 
     private
@@ -168,5 +185,20 @@ module AgentAdmit
     rescue StandardError
       nil
     end
+
+    def report_outcome_after_response(result, response)
+      return unless result.audit_row_id
+      return unless response.is_a?(Array) && response.length >= 3
+
+      status_class = IntrospectionClient.status_class_for(response[0])
+      outcome = IntrospectionClient.outcome_for_status(response[0])
+      return unless status_class && outcome
+
+      @client.report_outcome(result.audit_row_id,
+                             outcome: outcome,
+                             status_class: status_class)
+    rescue StandardError => e
+      warn "[AgentAdmit] Outcome report failed: #{e.message}"
+    end
   end
 end

data/lib/agentadmit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentAdmit
-  VERSION = "1.12.0"
+  VERSION = "1.13.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: agentadmit
 version: !ruby/object:Gem::Version
-  version: 1.12.0
+  version: 1.13.0
 platform: ruby
 authors:
 - Christopher Emerson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json