agentadmit 1.12.0 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35cfc75d6a091ef7f5940c488c472efad1c6d48a68c670e6c5e1522dbe9abb06
-  data.tar.gz: 0a9c2ecbc1fcdab6255e709519625cc1dbc9944d36d2b9725d5069a44544b222
+  metadata.gz: 4614ce271d54fa958f580f2180349bbdad92764566efe17d3a459c0fca62815c
+  data.tar.gz: 5c46517cd626d99eda4482cf47fdb14ae98b13f9a451216bcb117f6fd236f9c8
 SHA512:
-  metadata.gz: 39bb513f8747187ffeb5d7bb73f4557c47a9da0a95f1bd8b56130f95b38406081befb47570f425afbdfbc1ca322069459c5ebf3e4fcb1f4c164320242c306882
-  data.tar.gz: 35577380cb5d5e783fe05e68c67c291238de414dd9b8fb99cb4d9ea8f75a5befed74c501ccd50e1a2eade6ffe3dc3d009d712ef5f44f1b1ba41e7928d8c20a99
+  metadata.gz: 716a550dd977efc852984419c4f79e8fba5e28fd282a3c5b8630251fc48dba14548ac6e1950d2c548057acf84862d9c023525cdfe1ba5e8c2ef60e5ca0d021a7
+  data.tar.gz: c568d905a1930f6376109751c2fe3c464a181049f359b50f280872f9b18042d82d75a73e628119ed0d8f51270bfa843b39ca4585f7867182c4ed3242d6d8000f

data/README.md

@@ -398,6 +398,29 @@ result.user_intent # => "Book my flights to the Austin offsite in October" or ni
 
 `user_intent` is nullable -- connections issued without one (or by servers that predate the field) read as `nil`. Months later, a review screen can answer "is this still appropriate?" with the user's own stated boundary, not just the app's. Like purpose, it is a review-time record and never an enforcement input; authorization decisions ride scopes, connection status, and consent.
 
+## Agent Designation
+
+On AgentAdmit's consent page the user says which agent app a connection is for and, optionally, which AI model family it mainly uses. That is the user's statement, recorded with the grant; it is not a verified identity of the agent. Separately, an agent may report its own platform and model when it redeems the connection token; that is unverified too.
+
+The verify response reports both on every introspection, and the SDK surfaces them on the result as `designated_agent` and `agent_reported` (`nil` when the connection carries none):
+
+```ruby
+result = AgentAdmit::IntrospectionClient.new.verify(token)
+
+# {"agent_id" => ..., "name" => ..., "source" => "user_declared",
+#  "model" => {"model_id" => ..., "name" => ...} or nil}
+named = result.designated_agent
+# {"platform" => ..., "model" => {"id" => ..., "version" => ...} or nil}
+reported = result.agent_reported
+
+puts "Named by the user: #{named ? named['name'] : '(not named)'}"
+puts "Reported by the agent: #{reported&.dig('model', 'id') || '(nothing)'}"
+```
+
+Use `designated_agent["name"]` when you tell a user which of their connections did something: it is the name they chose. `agent_id` and `model["model_id"]` are the ids of your list entries, or `nil` when the user typed a name that is not on your list.
+
+Do not branch authorization on either field. They are records for people reviewing a connection, not a gate. Scope checks, connection status, and consent verdicts remain the only decision inputs. To act on a designation, use the hosted revoke API (`designated_agent_id`, `designated_model_id`) or your list's block setting in the dashboard.
+
 ## App-Attested Presence
 
 If your app gates token minting behind its own embedded passkey/WebAuthn ceremony, AgentAdmit never witnesses that ceremony (it is origin-bound), so by default the hosted service reports `presence.verified: false` for those connections. Attest the ceremony fact at issuance to close that gap -- AFTER verifying and consuming your own fresh, purpose-bound attestation:
@@ -449,6 +472,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,15 @@ 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, :designated_agent,
+                                     :agent_reported, keyword_init: true) do
       def has_scope?(scope)
         scopes.include?(scope)
       end
@@ -83,9 +87,48 @@ 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.
+
+      # `designated_agent` (Hash or nil) is what the USER said on AgentAdmit's
+      # consent page: which agent app the connection is for and, optionally,
+      # which AI model family it mainly uses:
+      # {"agent_id" => String|nil, "name" => String,
+      #  "source" => "user_declared",
+      #  "model" => {"model_id" => String|nil, "name" => String} | nil}.
+      # It is the user's statement, recorded with the grant; it is not a
+      # verified identity of the agent. `agent_id` / `model_id` are nil when
+      # the user typed a name that is not on the app's list.
+
+      # `agent_reported` (Hash or nil) is what the AGENT reported about itself
+      # when it redeemed the connection token:
+      # {"platform" => String|nil,
+      #  "model" => {"id" => String, "version" => String|nil} | nil}.
+      # Unverified. Both fields are review-time records only, never an
+      # enforcement input; authorization decisions ride scopes, connection
+      # status, and consent.
     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 +194,75 @@ 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 user's agent designation from a verify response, or nil when the
+      # block is absent, null, or not a user-declared designation. Strict: a
+      # non-empty String name and source "user_declared", or the whole block
+      # is dropped. A malformed model is dropped and the app is kept. This is
+      # what the user said on the consent page, not a verified identity.
+      #
+      # @param raw [Object] the `designated_agent` value from the verify body
+      # @return [Hash, nil]
+      #
+      def parse_designated_agent(raw)
+        return nil unless raw.is_a?(Hash)
+        name = raw["name"]
+        return nil unless name.is_a?(String) && !name.empty?
+        return nil unless raw["source"] == "user_declared"
+
+        m = raw["model"]
+        model =
+          if m.is_a?(Hash) && m["name"].is_a?(String) && !m["name"].empty?
+            { "model_id" => m["model_id"].is_a?(String) ? m["model_id"] : nil,
+              "name"     => m["name"] }
+          end
+
+        { "agent_id" => raw["agent_id"].is_a?(String) ? raw["agent_id"] : nil,
+          "name"     => name,
+          "source"   => "user_declared",
+          "model"    => model }
+      end
+
+      ##
+      # What the agent reported about itself at token exchange, or nil when
+      # the block carries neither a platform nor a model id. Unverified.
+      #
+      # @param raw [Object] the `agent_reported` value from the verify body
+      # @return [Hash, nil]
+      #
+      def parse_agent_reported(raw)
+        return nil unless raw.is_a?(Hash)
+
+        platform = raw["platform"]
+        platform = nil unless platform.is_a?(String) && !platform.empty?
+        m = raw["model"]
+        model =
+          if m.is_a?(Hash) && m["id"].is_a?(String) && !m["id"].empty?
+            { "id"      => m["id"],
+              "version" => m["version"].is_a?(String) ? m["version"] : nil }
+          end
+        return nil if platform.nil? && model.nil?
+
+        { "platform" => platform, "model" => model }
+      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 +475,17 @@ 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"])
+
+        # Agent designation (1.14.0): what the user said the connection is
+        # for, and what the agent reported about itself. Review-time records,
+        # never an enforcement input, so a malformed block is dropped rather
+        # than failing the verify.
+        designated_agent = self.class.parse_designated_agent(data["designated_agent"])
+        agent_reported = self.class.parse_agent_reported(data["agent_reported"])
+
         return IntrospectionResult.new(
           user_id:      data["user_id"],
           connection_id: data["connection_id"],
@@ -377,7 +500,11 @@ 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,
+          designated_agent: designated_agent,
+          agent_reported: agent_reported
         )
       end
 
@@ -385,6 +512,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.14.0"
 end

metadata

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