agentadmit 1.13.0 → 1.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d3b45175d51202f94a44cfda45acd2eedbd6e96453686633e2c23fe1e9e4b07
-  data.tar.gz: 8e6e17f6848db25e36996afcb1e16ed45ec0ab591647cdc9bbd56f51b1b1957d
+  metadata.gz: 1af95260c413c1ce419cfdd29dbb64abffa228c2c252d729f62d8d8514713d43
+  data.tar.gz: c9a638031a64b6d5a634687f0d8bd150b928ff10e76af2b6203215c908aae7c6
 SHA512:
-  metadata.gz: e77aed424389ce8a3c15445505cf32cadad2f04a004d4eb003b06c07891556c1968dda9c27506045ea7762c054f31b26c5c7271b79c96fc696423edee7655a6f
-  data.tar.gz: 4526e4389bc7dad6a0799d0633082f9c885afff37c4aaa80be55065856d82a507bf12d20270e27cb636a057342995e880aeaa5734edfbfe8bd67e2110cb61223
+  metadata.gz: e12e4ede6e53c77634ef65d249a5e8363ba9a2a7bba650fe9a3b5696410dbe30a90c170bdd44ac1a44dbe8b7c0fa5145b8fa4d1ae5c8d47084d5f2e2e6d4f0e4
+  data.tar.gz: d6c0bfb352a0af3044b8153846969b0e9500e13d7a82489d06ad80383bc0b171156bbe5a95e84913c43b21f11127523342359f6f9939a0ba5e3b1ea8f004e6f1

data/README.md

@@ -398,6 +398,31 @@ 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.
+
+If your code redeems connection tokens with `TokensClient#exchange`, pass `agent_platform:` and `agent_model:` to send along what the agent says it runs on (since 1.14.1).
+
+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:

data/lib/agentadmit/introspection_client.rb

@@ -34,7 +34,8 @@ module AgentAdmit
                                      :sub, :role, :app_id, :jti, :exp, :consent,
                                      :presence, :purpose, :user_intent,
                                      :action_confirmation, :audit_row_id,
-                                     :consumed_receipt, keyword_init: true) do
+                                     :consumed_receipt, :designated_agent,
+                                     :agent_reported, keyword_init: true) do
       def has_scope?(scope)
         scopes.include?(scope)
       end
@@ -94,6 +95,24 @@ module AgentAdmit
       # `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
@@ -192,6 +211,58 @@ module AgentAdmit
           "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
@@ -408,6 +479,13 @@ module AgentAdmit
         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"],
@@ -424,7 +502,9 @@ module AgentAdmit
           user_intent:  user_intent,
           action_confirmation: action_confirmation,
           audit_row_id: audit_row_id,
-          consumed_receipt: consumed_receipt
+          consumed_receipt: consumed_receipt,
+          designated_agent: designated_agent,
+          agent_reported: agent_reported
         )
       end
 

data/lib/agentadmit/tokens_client.rb

@@ -111,13 +111,22 @@ module AgentAdmit
     # @param connection_token [String] the ag_ct_… connection token
     # @param agent_label [String, nil] human-readable agent name
     # @param agent_id [String, nil] agent identifier
+    # @param agent_platform [String, nil] the agent app or runtime the agent
+    #   says it runs in (reported by the agent, unverified)
+    # @param agent_model [Hash, nil] the AI model the agent says it runs on:
+    #   {"id" => String, "version" => String (optional)} (reported by the
+    #   agent, unverified). The hosted service records both and never lets
+    #   them decide the outcome of the exchange.
     # @return [Hash] the exchange response — "access_token" is the ag_at_… token
     # @raise [IntrospectionError] if the exchange fails
     #
-    def exchange(connection_token, agent_label: nil, agent_id: nil)
+    def exchange(connection_token, agent_label: nil, agent_id: nil,
+                 agent_platform: nil, agent_model: nil)
       body = { "token" => connection_token }
       body["agent_label"] = agent_label if agent_label
       body["agent_id"] = agent_id if agent_id
+      body["agent_platform"] = agent_platform if agent_platform
+      body["agent_model"] = agent_model if agent_model
 
       post("/api/v1/exchange", body, authenticated: false, op: "exchange")
     end

data/lib/agentadmit/version.rb

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

metadata

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