teams_rb 2.0.2 → 2.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3d8a62ece3135e07d8e1bd653ffbce95e706c4c318b96f69c4065f4c55b96b5
-  data.tar.gz: 47b7b2e70aebbe6509b68cf4af7df807e1e30de1b02739494ff781589181c554
+  metadata.gz: 1502c7094dd98f8e69bfc496dbc8887273cda01eefb1729ff20d480f2e490d24
+  data.tar.gz: 13bdd7a69d783a0e7421c0ea9a2d1b6e5c364dfd89b1ccdbb38c7afa832008a6
 SHA512:
-  metadata.gz: cb518ff2d7c087f4b2e07ac866525b9ccdc4fc5583a012c920b563b7e04b428d8523826ae13a1c7b3d2500a5584caebd529ca9fe83de6752010c43ee6e5698ca
-  data.tar.gz: a7875d84333fea72c4c3d1ccaadc2ecd59731f3314a50a6838278db81e41945844e6f2e9d5511b987135912cb1a5695ab9a90ee3793f393d8945e1d18408d52e
+  metadata.gz: cceee102720b9bee0243602582c815ba0deeb3b8b23f7580c324b72b6b1a4431083ec68926677887acd4d3780520d31be30460499d9d2868b1adeb9f60ef671e
+  data.tar.gz: 71df520f4b46f72ec60919a9c0cf2403d5a0e7b5e7118503130a3ca9e77cd8d933a5841040078ddde03c8188a06a6db4c8e369e1c7e334237c0e6db432c74433

data/CHANGELOG.md

@@ -6,6 +6,29 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [2.0.3] - 2026-11-05
+
+### Added
+
+- `Api::AgenticIdentity` and agentic account fields (`agentic_user_id`, `agentic_app_id`, `agentic_app_blueprint_id`, `callback_uri`, plus an `agentic_identity` helper on `Api::Account`) for Agent 365 activities, matching the TypeScript, Python, and .NET SDKs
+- Inbound activity validation now accepts Entra-issued agent tokens: validated against the token's own tenant (bounded per-tenant JWKS caching) with the same three audience forms; the Bot Framework service-token path and the remote-function validation path are unchanged. Entra inbound tokens carry no `serviceurl` claim, so that check applies only to service tokens
+- `CloudEnvironment#agent_bot_scope` (`https://botapi.skype.com/.default`)
+- `on_agent_lifecycle` plus per-variant routes (`on_agentic_user_identity_created`/`identity_updated`/`manager_updated`/`enabled`/`disabled`/`deleted`/`undeleted`/`workload_onboarding_updated`) for Agent 365 `agentLifecycle` events, discriminated on the activity's `valueType`, with value readers for the lifecycle payload fields
+- Agentic operation (experimental): inbound activities addressed to an agentic user scope the whole turn — context, sends, and streaming — to that identity; `app.agentic_identity` builds identities for proactive work, `post`/`reply`/`update` accept `agentic_identity:`, and `Api::Client#for_agentic_identity` returns an identity-scoped client. Agentic tokens use the three-step Agent 365 exchange (blueprint assertion with `fmi_path`, agentic-app client assertion, user federated-identity grant)
+- GitHub Actions CI runs the test suite and gem build for pull requests and pushes to main ([#11](https://github.com/bavmind/teams_rb/pull/11), thanks [@dblock](https://github.com/dblock))
+
+### Changed
+
+- Use the `jwt` gem (new runtime dependency, `~> 3.3`) for inbound JWT decoding, JWK import, RS256 verification, and standard claim validation instead of handwritten token parsing and RSA key construction ([#12](https://github.com/bavmind/teams_rb/pull/12), thanks [@dblock](https://github.com/dblock))
+- Match the TypeScript SDK's signing-key cache defaults: cache up to five keys per JWKS endpoint for ten minutes, fetch uncached keys immediately without rate limiting or negative caching, and reject key-fetch failures as authentication errors ([#12](https://github.com/bavmind/teams_rb/pull/12), thanks [@dblock](https://github.com/dblock))
+- Allow five minutes of clock tolerance for inbound JWT expiry and not-before validation, matching the TypeScript, Python, and .NET SDKs ([#12](https://github.com/bavmind/teams_rb/pull/12), thanks [@dblock](https://github.com/dblock))
+
+### Fixed
+
+- Recover from signing-key rotation without restarting the bot instead of caching the first JWKS document indefinitely ([#14](https://github.com/bavmind/teams_rb/issues/14), [#12](https://github.com/bavmind/teams_rb/pull/12), thanks [@dblock](https://github.com/dblock))
+- Avoid blocking cached signing-key validation behind slow JWKS or discovery requests while preserving coordinated successful cache misses ([#12](https://github.com/bavmind/teams_rb/pull/12), thanks [@dblock](https://github.com/dblock))
+- Duplicate `signin/tokenExchange` invokes are deduplicated on the exchange id: each Teams client (desktop, web, mobile) rendering the OAuth card attempts its own silent exchange, and previously each successful one fired `on_sign_in`. Now only the first runs the exchange; duplicates answer 200 without re-emitting, an in-flight duplicate waits for the first result, and failed exchanges are not marked so retries still work. Follows the same fix in the TypeScript SDK (.NET already deduplicated)
+
 ## [2.0.2] - 2026-08-06
 
 ### Added
@@ -64,7 +87,8 @@ the Python SDK made when it joined the family.
 - Thread-safe token management, storage, and JWKS caching for multi-threaded Rack servers
 - Documentation mirroring the official teams-sdk docs structure (getting started, essentials, in-depth guides)
 
-[Unreleased]: https://github.com/bavmind/teams_rb/compare/v2.0.2...HEAD
+[Unreleased]: https://github.com/bavmind/teams_rb/compare/v2.0.3...HEAD
+[2.0.3]: https://github.com/bavmind/teams_rb/compare/v2.0.2...v2.0.3
 [2.0.2]: https://github.com/bavmind/teams_rb/compare/v2.0.1...v2.0.2
 [2.0.1]: https://github.com/bavmind/teams_rb/compare/v2.0.0...v2.0.1
 [2.0.0]: https://github.com/bavmind/teams_rb/releases/tag/v2.0.0

data/README.md

@@ -1,6 +1,7 @@
 # teams_rb — Teams SDK for Ruby
 
 [![Gem Version](https://img.shields.io/gem/v/teams_rb)](https://rubygems.org/gems/teams_rb)
+[![CI](https://github.com/bavmind/teams_rb/actions/workflows/ci.yml/badge.svg)](https://github.com/bavmind/teams_rb/actions/workflows/ci.yml)
 [![Documentation](https://img.shields.io/badge/docs-getting_started-blue)](docs/getting-started/README.md)
 
 A Ruby-native port of the Microsoft Teams SDKs for building Teams bots and apps with Rack or Rails. It includes message routing, proactive messaging, the Bot Framework API client, typed Adaptive Cards, dialogs, message extensions, streaming, meetings, OAuth, Microsoft Graph, tabs, and remote functions.
@@ -146,6 +147,8 @@ bundle install
 bundle exec rake test
 ```
 
+GitHub Actions runs `bundle exec rake ci` on pushes and pull requests using Ruby 4.0. This runs the full test suite and builds the gem; use the same command locally to check both.
+
 The gem is self-contained. Regenerating the typed Adaptive Card classes requires a sibling checkout of Microsoft's Python SDK; see the [Adaptive Cards guide](docs/in-depth-guides/adaptive-cards.md#regenerating).
 
 ## Questions and issues

data/docs/essentials/app-authentication.md

@@ -1,19 +1,29 @@
 # App authentication
 
-How the app proves itself to Teams, and how Teams proves itself to the app. All of it matches the TypeScript, Python, and .NET SDKs.
+How the app proves itself to Teams, and how Teams proves itself to the app.
 
 ## Inbound validation
 
-Every `POST /api/messages` request must carry a Bot Framework JWT. The app validates:
+Every `POST /api/messages` request must carry a Bot Framework JWT. Token decoding, JWK import, RS256 signature verification, and standard claims use the established [`jwt` gem](https://github.com/jwt/ruby-jwt); Teams-specific endpoint selection, signing-key caching, and service URL checks remain in this SDK.
+
+The app validates:
 
 - **Signature** against Microsoft's published signing keys (RS256, JWKS fetched and cached)
 - **Issuer** — the Bot Framework issuer, or your tenant's Entra issuers (v1 and v2 forms) when `TENANT_ID` is configured
 - **Audience** — your app id, in any of the three accepted forms: the bare id, `api://{id}`, `api://botid-{id}`
-- **Expiry / not-before**
+- **Expiry / not-before** with five minutes of clock tolerance, matching the JavaScript Teams SDK
 - **`serviceurl` claim** — must match the activity's service URL, preventing spoofed routing
 
 Rejected requests get a 401 with a warn log line. Requests are rejected wholesale when no credentials are configured (with a loud startup warning) unless `dangerously_allow_unauthenticated_requests: true` is set explicitly — which is for local development only. The option can also come from the `DANGEROUSLY_ALLOW_UNAUTHENTICATED_REQUESTS` environment variable (`true`/`false`, `1`/`0`, `yes`/`no`, or `on`/`off`); the older `skip_auth:` name still works as a deprecated alias.
 
+### Signing-key caching and rotation
+
+The signing-key cache follows the defaults used by the [JavaScript Teams SDK](https://github.com/microsoft/teams.js/blob/3420e8899e71ed7cc74711d62f07c25e73d45b42/packages/apps/src/middleware/auth/jwt-validator.ts) and its [`jwks-rsa` 4.1.0 dependency](https://github.com/auth0/node-jwks-rsa/blob/v4.1.0/src/wrappers/cache.js): each JWKS endpoint has a least-recently-used cache of at most five public keys, indexed by JWT `kid`. Only the requested key is cached, even when a downloaded key document contains several keys.
+
+Keys expire ten minutes after retrieval. Cache hits update recency but do not extend expiry. An uncached or expired key triggers a fresh JWKS fetch immediately, including when another key was fetched moments earlier. Misses are coordinated per JWKS endpoint, and waiting requests recheck the cache to share successful lookups. Cache reads and updates take only a brief shared mutex; HTTP requests run outside it, and Bot Framework discovery has separate synchronization. A slow key fetch or discovery request therefore does not block verification with another unexpired cached key. There is no background refresh, negative caching, retry cooldown, or fetch rate limit, matching the JavaScript SDK's current configuration. Arbitrary unknown key IDs can therefore cause repeated outbound requests; account for this when protecting your bot endpoint.
+
+Key-fetch, discovery, and malformed key-response failures reject authentication with HTTP 401 and a warn log line through the Rack adapter. Failed lookups are not cached and may be retried immediately. Other unexpired cached keys remain usable, but expired keys are never used as a fallback during an outage. Bot Framework discovery still resolves `jwks_uri` once per validator; tenant keys still use the configured tenant endpoint. Existing issuer, audience, service URL, and RS256 checks remain in place; this matches JavaScript's cache defaults, not every feature of its authentication stack.
+
 ## Outbound bot tokens
 
 Replies and proactive sends authenticate with an app-only token from the Entra client-credentials flow, acquired and cached automatically (single-flight refresh with expiry skew — the other SDKs get the equivalent from MSAL). Nothing to configure beyond the three credentials.

data/docs/essentials/on-activity.md

@@ -46,6 +46,19 @@ teams.on_team_renamed     { |ctx| }        # also: on_team_archived, on_team_una
 
 A generic `on_conversation_update` registered before a specific route sees the activity first; declare `|ctx, nxt|` and call `nxt.call` to continue to the specific route (see Middleware below).
 
+## Agent 365 lifecycle events
+
+`on_agent_lifecycle` matches any `agentLifecycle` event (sent when this app runs as an Agent 365 agentic user); the variants also have named routes, matched on the activity's `valueType`:
+
+```ruby
+teams.on_agent_lifecycle { |ctx| }                # any agentLifecycle event
+teams.on_agentic_user_identity_created { |ctx| }  # also: identity_updated, manager_updated,
+teams.on_agentic_user_enabled { |ctx| }           #   disabled, deleted, undeleted,
+                                                  #   workload_onboarding_updated
+```
+
+The event value exposes `tenant_id`, `agentic_user_id`, `agentic_app_instance_id`, `agent_identity_blueprint_id`, `version`, and per-variant fields (`manager`, `deletion_reason`, `workload_name`, …).
+
 ## Meeting events
 
 ```ruby

data/docs/in-depth-guides/README.md

@@ -10,5 +10,6 @@ Feature guides for building richer Teams apps:
 - [Streaming](streaming.md) — chunked responses, informative updates, events, typed errors
 - [User authentication](user-authentication.md) — OAuth sign-in, token exchange, Azure setup
 - [Tabs and remote functions](tabs.md) — calling the bot backend from a tab with SSO
+- [Agent 365](agent-365.md) — running as an agentic user (experimental)
 - [Meeting events](meeting-events.md) — meeting start/end
 - [Observability](observability.md) — logging and middleware

data/docs/in-depth-guides/agent-365.md

@@ -0,0 +1,46 @@
+# Agent 365 (experimental)
+
+> Agent 365 support is experimental across the whole Teams SDK family. Expect
+> changes.
+
+Agent 365 gives an app a *stacked identity*: the app registration acts as an
+**agentic app blueprint** (its client id *is* the blueprint id), a tenant can
+instantiate **agentic apps** from it, and each app can carry **agentic users**
+— user-shaped Entra identities that appear in Teams like people.
+
+## Inbound
+
+Nothing to configure. When Teams delivers an activity to an agentic user, the
+identity arrives on the activity's `recipient` account and the request carries
+an Entra-issued token (accepted automatically alongside classic Bot Framework
+tokens). The SDK scopes the whole turn to that identity — `ctx.post`, replies,
+and streaming authenticate as the agent, not the app:
+
+```ruby
+teams.on_message do |ctx|
+  identity = ctx.activity.recipient.agentic_identity
+  ctx.log.info "acting as agentic user #{identity.agentic_user_id}" if identity
+  ctx.reply "Hello from your agent"
+end
+```
+
+## Lifecycle events
+
+Teams reports agentic-user lifecycle changes as `agentLifecycle` events — see
+[activity routing](../essentials/on-activity.md) for `on_agent_lifecycle` and
+the per-variant routes.
+
+## Proactive
+
+Build the identity explicitly (the blueprint defaults to the app's client id,
+the tenant to the configured credentials tenant) and pass it to the proactive
+senders:
+
+```ruby
+identity = teams.agentic_identity(agentic_app_id: "...", agentic_user_id: "...")
+teams.post(conversation_id, "Proactive hello from the agent", agentic_identity: identity)
+```
+
+Omitting `agentic_user_id` acts as the agentic app itself. There is no
+fallback between identity kinds: if an agentic token cannot be acquired the
+call fails rather than silently sending as the wrong identity.

data/lib/teams/activity.rb

@@ -16,6 +16,11 @@ module Teams
       raw["name"]
     end
 
+    # Discriminates agentLifecycle event variants (PascalCase wire values).
+    def value_type
+      raw["valueType"] || raw["value_type"]
+    end
+
     def text
       raw["text"]
     end

data/lib/teams/activity_context.rb

@@ -7,12 +7,13 @@ module Teams
   class ActivityContext
     attr_reader :app, :activity, :conversation_reference, :extra, :stream
 
-    def initialize(app:, activity:, conversation_reference:, extra: {}, stream: nil)
+    def initialize(app:, activity:, conversation_reference:, extra: {}, stream: nil, api: nil)
       @app = app
       @activity = activity
       @conversation_reference = conversation_reference
       @extra = extra
       @stream = stream
+      @api = api
     end
 
     def ref
@@ -31,15 +32,17 @@ module Teams
       app.storage
     end
 
+    # The turn's API client; scoped to the activity's agentic identity when
+    # the app runs as an Agent 365 agent.
     def api
-      app.api
+      @api || app.api
     end
 
     # The TypeScript, Python, and .NET SDKs call this operation `send`.
     # Ruby already defines Object#send for dynamic dispatch, so the public
     # Ruby API uses `post` to avoid shadowing a core language method.
     def post(activity_or_text)
-      app.send_activity(conversation_reference, apply_targeted_defaults(activity_or_text))
+      app.send_activity(conversation_reference, apply_targeted_defaults(activity_or_text), api:)
     end
 
     def reply(activity_or_text)
@@ -140,7 +143,7 @@ module Teams
         ]
       }
 
-      app.send_activity(conversation_reference, payload)
+      app.send_activity(conversation_reference, payload, api:)
       nil
     end
 

data/lib/teams/api/account.rb

@@ -55,6 +55,36 @@ module Teams
         read("tenantId", "tenant_id")
       end
 
+      def agentic_user_id
+        read("agenticUserId", "agentic_user_id")
+      end
+
+      def agentic_app_id
+        read("agenticAppId", "agentic_app_id")
+      end
+
+      def agentic_app_blueprint_id
+        read("agenticAppBlueprintId", "agentic_app_blueprint_id")
+      end
+
+      def callback_uri
+        read("callbackUri", "callback_uri")
+      end
+
+      # The Agent 365 identity scope this account carries (agentic accounts
+      # arrive with role "agenticUser" on the activity's recipient); nil
+      # unless the account belongs to an agentic app blueprint.
+      def agentic_identity
+        return nil unless agentic_app_blueprint_id
+
+        AgenticIdentity.new(
+          agentic_app_blueprint_id:,
+          agentic_app_id:,
+          agentic_user_id:,
+          tenant_id:
+        )
+      end
+
       def to_h
         body = raw.dup
         body["id"] = id if id
@@ -70,6 +100,10 @@ module Teams
         body["email"] = email if email
         body["userPrincipalName"] = user_principal_name if user_principal_name
         body["tenantId"] = tenant_id if tenant_id
+        body["agenticUserId"] = agentic_user_id if agentic_user_id
+        body["agenticAppId"] = agentic_app_id if agentic_app_id
+        body["agenticAppBlueprintId"] = agentic_app_blueprint_id if agentic_app_blueprint_id
+        body["callbackUri"] = callback_uri if callback_uri
         remove_aliases(body)
       end
 
@@ -83,6 +117,10 @@ module Teams
         body.delete("given_name")
         body.delete("user_principal_name")
         body.delete("tenant_id")
+        body.delete("agentic_user_id")
+        body.delete("agentic_app_id")
+        body.delete("agentic_app_blueprint_id")
+        body.delete("callback_uri")
         body
       end
     end

data/lib/teams/api/activity_value.rb

@@ -73,6 +73,69 @@ module Teams
       def top
         read("top")
       end
+
+      # Agent 365 agentLifecycle event value fields. The service sends the
+      # agenticAppInstanceId / agentIdentityBlueprintId wire keys (not the
+      # account-style names); all SDKs preserve them.
+      def tenant_id
+        read("tenantId", "tenant_id")
+      end
+
+      def agentic_user_id
+        read("agenticUserId", "agentic_user_id")
+      end
+
+      def agentic_app_instance_id
+        read("agenticAppInstanceId", "agentic_app_instance_id")
+      end
+
+      def agent_identity_blueprint_id
+        read("agentIdentityBlueprintId", "agent_identity_blueprint_id")
+      end
+
+      def version
+        read("version")
+      end
+
+      # Variant extras: manager (identity-created carries userId/email/
+      # displayName; manager-updated carries managerId), deletion reason,
+      # workload onboarding fields, and the created identity's expiry.
+      def manager
+        value = read("manager")
+        value.is_a?(Hash) ? ActivityValue.new(value) : value
+      end
+
+      def user_id
+        read("userId", "user_id")
+      end
+
+      def email
+        read("email")
+      end
+
+      def display_name
+        read("displayName", "display_name")
+      end
+
+      def manager_id
+        read("managerId", "manager_id")
+      end
+
+      def deletion_reason
+        read("deletionReason", "deletion_reason")
+      end
+
+      def workload_name
+        read("workloadName", "workload_name")
+      end
+
+      def workload_onboarding_state
+        read("workloadOnboardingState", "workload_onboarding_state")
+      end
+
+      def expiration_date_time
+        read("expirationDateTime", "expiration_date_time")
+      end
     end
   end
 end

data/lib/teams/api/agentic_identity.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Teams
+  module Api
+    # The Agent 365 identity scope for SDK operations: an agentic app
+    # blueprint (the app registration itself), optionally narrowed to an
+    # agentic app instance and an agentic user attached to that instance.
+    class AgenticIdentity
+      attr_reader :agentic_app_blueprint_id, :agentic_app_id, :agentic_user_id, :tenant_id
+
+      def initialize(agentic_app_blueprint_id:, agentic_app_id: nil, agentic_user_id: nil, tenant_id: nil)
+        @agentic_app_blueprint_id = agentic_app_blueprint_id
+        @agentic_app_id = agentic_app_id
+        @agentic_user_id = agentic_user_id
+        @tenant_id = tenant_id
+      end
+
+      def to_h
+        body = { "agenticAppBlueprintId" => agentic_app_blueprint_id }
+        body["agenticAppId"] = agentic_app_id if agentic_app_id
+        body["agenticUserId"] = agentic_user_id if agentic_user_id
+        body["tenantId"] = tenant_id if tenant_id
+        body
+      end
+    end
+  end
+end

data/lib/teams/api/client.rb

@@ -12,17 +12,41 @@ module Teams
       # Sub-clients are constructed eagerly like the other SDKs' ApiClient
       # constructors, which also keeps the shared client thread-safe.
       # oauth_url is the Bot Framework token service (cloud-dependent), used
-      # by the user token and bot sign-in clients.
-      def initialize(service_url:, http:, logger: nil, oauth_url: DEFAULT_OAUTH_URL)
+      # by the user token and bot sign-in clients. token_provider is a
+      # callable(agentic_identity) returning a bearer token; it enables
+      # for_agentic_identity scoping (the App wires it to its TokenManager).
+      def initialize(service_url:, http:, logger: nil, oauth_url: DEFAULT_OAUTH_URL, token_provider: nil)
         @service_url = service_url.sub(%r{/+\z}, "")
         @http = http
         @logger = logger
+        @oauth_url = oauth_url
+        @token_provider = token_provider
         @conversations = ConversationClient.new(service_url: @service_url, http:, logger:)
         @teams = TeamClient.new(service_url: @service_url, http:, logger:)
         @meetings = MeetingClient.new(service_url: @service_url, http:, logger:)
         @users = UserClient.new(oauth_url:, http:, logger:)
         @bots = BotClient.new(oauth_url:, http:, logger:)
       end
+
+      # Returns a client scoped to an Agent 365 identity (and optionally a
+      # different service URL): requests authenticate with the identity's
+      # agentic token instead of the app token. The other SDKs call this
+      # clone(); Ruby avoids shadowing Object#clone, like post vs send.
+      # A nil identity scopes back to the app token.
+      def for_agentic_identity(agentic_identity, service_url: nil)
+        unless @token_provider
+          raise Error, "This API client was constructed without a token provider; agentic scoping is unavailable."
+        end
+
+        identity = agentic_identity
+        self.class.new(
+          service_url: service_url || @service_url,
+          http: Common::HttpClient.new(token: -> { @token_provider.call(identity) }),
+          logger: @logger,
+          oauth_url: @oauth_url,
+          token_provider: @token_provider
+        )
+      end
     end
   end
 end

data/lib/teams/app.rb

@@ -6,6 +6,7 @@ module Teams
   class App
     DEFAULT_MESSAGING_ENDPOINT = "/api/messages"
     DANGEROUSLY_ALLOW_UNAUTHENTICATED_REQUESTS_ENV_VAR = "DANGEROUSLY_ALLOW_UNAUTHENTICATED_REQUESTS"
+    MAX_PROCESSED_EXCHANGE_IDS = 1000
     TRUE_ENV_VALUES = %w[1 true yes on].freeze
     FALSE_ENV_VALUES = %w[0 false no off].freeze
 
@@ -48,7 +49,8 @@ module Teams
         service_url:,
         http: Common::HttpClient.new(token: -> { @token_manager.bot_token }),
         logger:,
-        oauth_url: cloud.token_service_url
+        oauth_url: cloud.token_service_url,
+        token_provider: method(:token_for_agentic_identity)
       )
       @jwt_validator = Auth::JwtValidator.new(
         client_id: @token_manager.client_id,
@@ -235,6 +237,21 @@ module Teams
       end
     end
 
+    # Agent 365 agentLifecycle events plus their per-variant routes
+    # (on_agentic_user_identity_created, on_agentic_user_enabled, ...),
+    # discriminated by the activity-level valueType.
+    def on_agent_lifecycle(&block)
+      @router.on_agent_lifecycle(&block)
+      self
+    end
+
+    Router::AGENT_LIFECYCLE_EVENTS.each_key do |method_name|
+      define_method(method_name) do |&block|
+        @router.public_send(method_name, &block)
+        self
+      end
+    end
+
     # Message extension handlers (on_message_ext_query, on_message_ext_submit,
     # on_message_ext_open, ...) route the composeExtension/* invokes with the
     # TypeScript/Python route names. Handler return values (typed responses
@@ -266,11 +283,17 @@ module Teams
       validate_inbound!(env, activity)
 
       conversation_reference = Api::ConversationReference.from_activity(activity)
+      # Agentic activities carry the identity on the recipient account; the
+      # whole turn (context and stream) is scoped to it so replies
+      # authenticate as the agent, like the other SDKs' per-turn clients.
+      agentic_identity = activity.recipient.agentic_identity
+      turn_api = agentic_identity ? api.for_agentic_identity(agentic_identity) : api
       context = ActivityContext.new(
         app: self,
         activity:,
         conversation_reference:,
-        stream: HttpStream.new(app: self, conversation_reference:)
+        api: turn_api,
+        stream: HttpStream.new(app: self, conversation_reference:, api: turn_api)
       )
       result = run_handlers(context)
       context.stream.close
@@ -283,21 +306,34 @@ module Teams
       Response.new(status: 200)
     end
 
+    # Builds an Api::AgenticIdentity for proactive agentic operations: the
+    # blueprint defaults to this app's client id and the tenant to the
+    # configured credentials tenant, like the Python SDK.
+    def agentic_identity(agentic_app_id: nil, agentic_user_id: nil, tenant_id: nil, agentic_app_blueprint_id: nil)
+      Api::AgenticIdentity.new(
+        agentic_app_blueprint_id: agentic_app_blueprint_id || client_id,
+        agentic_app_id:,
+        agentic_user_id:,
+        tenant_id: tenant_id || @token_manager.credentials&.tenant_id
+      )
+    end
+
     # The TypeScript, Python, and .NET SDKs call this operation `send`.
     # Ruby already defines Object#send for dynamic dispatch, so the public
     # Ruby API uses `post` to avoid shadowing a core language method.
-    def post(conversation_id, activity_or_text, service_url: nil)
+    def post(conversation_id, activity_or_text, service_url: nil, agentic_identity: nil)
       assert_string!(conversation_id, "conversation_id")
 
       send_activity(
         proactive_reference(conversation_id, service_url:),
-        activity_or_text
+        activity_or_text,
+        api: agentic_identity ? api.for_agentic_identity(agentic_identity) : api
       )
     end
 
     # Proactive threaded replies use a ";messageid=" conversation ID like the
     # TypeScript and Python SDKs; the service decides whether threading applies.
-    def reply(conversation_id, activity_id_or_activity, activity_or_text = nil, service_url: nil)
+    def reply(conversation_id, activity_id_or_activity, activity_or_text = nil, service_url: nil, agentic_identity: nil)
       assert_string!(conversation_id, "conversation_id")
 
       if activity_or_text
@@ -306,23 +342,24 @@ module Teams
         post(
           Teams.to_threaded_conversation_id(conversation_id, activity_id_or_activity),
           activity_or_text,
-          service_url:
+          service_url:,
+          agentic_identity:
         )
       else
-        post(conversation_id, activity_id_or_activity, service_url:)
+        post(conversation_id, activity_id_or_activity, service_url:, agentic_identity:)
       end
     end
 
     # Sugar over post: the SDKs update by sending an activity that already
     # carries an id, and post does exactly that. See AGENTS.md.
-    def update(conversation_id, activity_id, activity_or_text, service_url: nil)
+    def update(conversation_id, activity_id, activity_or_text, service_url: nil, agentic_identity: nil)
       assert_string!(conversation_id, "conversation_id")
       assert_string!(activity_id, "activity_id")
 
-      post(conversation_id, activity_with_id(activity_id, activity_or_text), service_url:)
+      post(conversation_id, activity_with_id(activity_id, activity_or_text), service_url:, agentic_identity:)
     end
 
-    def send_activity(conversation_reference, activity_or_text)
+    def send_activity(conversation_reference, activity_or_text, api: self.api)
       activity = activity_for_reference(conversation_reference, activity_or_text)
       targeted = targeted_activity?(activity)
 
@@ -426,7 +463,18 @@ module Teams
     def register_default_oauth_handlers
       app = self
 
-      @router.on_signin_token_exchange do |ctx, nxt|
+      # Each Teams client (desktop, web, mobile) that renders the OAuth card
+      # attempts its own silent exchange, so one sign-in can produce several
+      # signin/tokenExchange invokes sharing the same value id. Only the first
+      # runs the exchange and fires sign-in; a duplicate of a completed
+      # exchange answers 200 without re-emitting or chaining, and a duplicate
+      # arriving while the first is in flight waits and returns its result.
+      # Failed exchanges are not marked, so each attempt gets its own 412.
+      exchange_mutex = Mutex.new
+      processed_exchange_ids = []
+      exchange_locks = {}
+
+      perform_token_exchange = lambda do |ctx, nxt|
         value = ctx.activity.value
         begin
           if value.raw["connectionName"] != app.default_connection_name
@@ -467,6 +515,43 @@ module Teams
         end
       end
 
+      @router.on_signin_token_exchange do |ctx, nxt|
+        exchange_id = ctx.activity.value.raw["id"]
+        next perform_token_exchange.call(ctx, nxt) unless exchange_id
+
+        lock = nil
+        duplicate = exchange_mutex.synchronize do
+          if processed_exchange_ids.include?(exchange_id)
+            true
+          else
+            lock = (exchange_locks[exchange_id] ||= { mutex: Mutex.new, settled: false, result: nil })
+            false
+          end
+        end
+        next Response.new(status: 200) if duplicate
+
+        outcome = lock[:mutex].synchronize do
+          if lock[:settled]
+            lock[:result]
+          else
+            result = perform_token_exchange.call(ctx, nxt)
+            if result.nil?
+              exchange_mutex.synchronize do
+                processed_exchange_ids << exchange_id
+                processed_exchange_ids.shift while processed_exchange_ids.length > MAX_PROCESSED_EXCHANGE_IDS
+              end
+              lock[:result] = Response.new(status: 200)
+            else
+              lock[:result] = result
+            end
+            lock[:settled] = true
+            result
+          end
+        end
+        exchange_mutex.synchronize { exchange_locks.delete(exchange_id) }
+        outcome
+      end
+
       @router.on_signin_verify_state do |ctx, nxt|
         begin
           state = ctx.activity.value.raw["state"]
@@ -562,12 +647,35 @@ module Teams
       end
     end
 
+    # Token dispatch for scoped API clients: no identity uses the app
+    # token; an identity with an agentic user uses the agentic user token;
+    # otherwise the agentic app token. Kinds never fall back to each other -
+    # failing is safer than authenticating under the wrong identity.
+    def token_for_agentic_identity(identity)
+      return @token_manager.bot_token unless identity
+
+      if identity.agentic_user_id
+        @token_manager.agentic_user_token(
+          @cloud.agent_bot_scope,
+          agentic_app_id: identity.agentic_app_id,
+          agentic_user_id: identity.agentic_user_id,
+          tenant_id: identity.tenant_id
+        )
+      else
+        @token_manager.agentic_app_token(
+          @cloud.agent_bot_scope,
+          agentic_app_id: identity.agentic_app_id,
+          tenant_id: identity.tenant_id
+        )
+      end
+    end
+
     def validate_inbound!(env, activity)
       return if @dangerously_allow_unauthenticated_requests
 
       raise AuthenticationError, "CLIENT_ID is required for inbound validation" unless @jwt_validator
 
-      @jwt_validator.validate!(env["HTTP_AUTHORIZATION"], service_url: activity.service_url)
+      @jwt_validator.validate_inbound_activity!(env["HTTP_AUTHORIZATION"], service_url: activity.service_url)
     end
 
     def run_handlers(context)

data/lib/teams/auth/jwt_validator.rb

@@ -1,56 +1,117 @@
 # frozen_string_literal: true
 
-require "base64"
-require "json"
-require "openssl"
+require "jwt"
 
 module Teams
   module Auth
     class JwtValidator
+      ENTRA_V1_ISSUER_PREFIX = "https://sts.windows.net/"
+      JWKS_CACHE_TTL = 10 * 60
+      JWKS_CACHE_MAX_ENTRIES = 5
+      # Endpoints are bounded so random tenant ids in unverified inbound
+      # tokens cannot grow the JWKS caches forever, like the
+      # TypeScript/Python validators.
+      MAX_JWKS_ENDPOINTS = 100
+      CLOCK_TOLERANCE = 5 * 60
+
       def initialize(client_id:, tenant_id: nil, cloud: PUBLIC_CLOUD, http: nil)
         @client_id = client_id
         @tenant_id = tenant_id
         @cloud = cloud
         @http = http || Common::HttpClient.new
         @jwks = {}
-        # The validator is shared across request threads; the mutex keeps
-        # concurrent cold-cache requests from fetching the JWKS repeatedly.
         @jwks_mutex = Mutex.new
+        # Coordinate misses per endpoint without blocking cached-key reads.
+        @jwks_fetch_mutexes = {}
+        @discovery_mutex = Mutex.new
       end
 
       def validate!(authorization_header, service_url: nil)
+        token = bearer_token!(authorization_header)
+        payload = decode!(token, issuers: valid_issuers) do |header, claims|
+          signing_key(jwks_uri_for_issuer(claims["iss"]), header["kid"])
+        end
+        validate_service_url!(payload, service_url) if service_url
+        payload
+      end
+
+      # Validates an inbound activity token. Classic bot activities carry
+      # Bot Framework service tokens and validate exactly like validate!;
+      # Agent 365 activities carry Entra tokens audienced to the agentic app
+      # blueprint, validated against the token's own tenant. The Entra path
+      # skips the serviceurl claim: agentic inbound tokens do not carry it
+      # (upstream revisits once the platform defines a signed equivalent).
+      def validate_inbound_activity!(authorization_header, service_url: nil)
+        token = bearer_token!(authorization_header)
+        claims = unverified_claims(token)
+        return validate_entra_inbound!(token, claims) if entra_issuer?(claims["iss"])
+
+        payload = decode!(token, issuers: valid_issuers) do |header, decoded|
+          signing_key(jwks_uri_for_issuer(decoded["iss"]), header["kid"])
+        end
+        validate_service_url!(payload, service_url) if service_url
+        payload
+      end
+
+      private
+
+      def bearer_token!(authorization_header)
         raise AuthenticationError, "Authorization header is required" if authorization_header.to_s.empty?
 
         scheme, token = authorization_header.split(" ", 2)
         raise AuthenticationError, "Authorization must be Bearer" unless scheme&.casecmp("Bearer")&.zero? && token
 
-        header, payload, signing_input, signature = decode(token)
-        validate_claims!(payload)
-        validate_service_url!(payload, service_url) if service_url
-        verify_signature!(header, signing_input, signature)
+        token
+      end
+
+      def decode!(token, issuers:)
+        payload, = JWT.decode(
+          token, nil, true,
+          algorithms: ["RS256"], leeway: CLOCK_TOLERANCE,
+          verify_expiration: true, verify_not_before: true,
+          verify_iss: true, iss: issuers,
+          verify_aud: true, aud: valid_audiences
+        ) do |header, claims|
+          raise AuthenticationError, "JWT payload must be an object" unless claims.is_a?(Hash)
+          unless header["kid"].nil? || header["kid"].is_a?(String)
+            raise AuthenticationError, "JWT signing key ID is invalid"
+          end
+
+          yield(header, claims)
+        end
         payload
+      rescue JWT::DecodeError => error
+        raise AuthenticationError, "JWT validation failed: #{error.message}"
       end
 
-      private
+      def unverified_claims(token)
+        claims, = JWT.decode(token, nil, false)
+        claims.is_a?(Hash) ? claims : {}
+      rescue JWT::DecodeError => error
+        raise AuthenticationError, "JWT validation failed: #{error.message}"
+      end
 
-      def decode(token)
-        header_segment, payload_segment, signature_segment = token.split(".")
-        raise AuthenticationError, "JWT must contain three segments" unless signature_segment
+      def entra_issuer?(issuer)
+        return false unless issuer.is_a?(String)
 
-        header = JSON.parse(Base64.urlsafe_decode64(pad(header_segment)))
-        payload = JSON.parse(Base64.urlsafe_decode64(pad(payload_segment)))
-        signature = Base64.urlsafe_decode64(pad(signature_segment))
-        [header, payload, "#{header_segment}.#{payload_segment}", signature]
-      rescue JSON::ParserError, ArgumentError
-        raise AuthenticationError, "JWT is malformed"
+        issuer.start_with?("#{@cloud.login_endpoint}/") || issuer.start_with?(ENTRA_V1_ISSUER_PREFIX)
       end
 
-      def validate_claims!(payload)
-        now = Time.now.to_i
-        raise AuthenticationError, "JWT expired" if payload["exp"] && now >= payload["exp"].to_i
-        raise AuthenticationError, "JWT not active yet" if payload["nbf"] && now < payload["nbf"].to_i
-        raise AuthenticationError, "JWT issuer is invalid" unless valid_issuer?(payload["iss"])
-        raise AuthenticationError, "JWT audience is invalid" if (Array(payload["aud"]) & valid_audiences).empty?
+      def validate_entra_inbound!(token, claims)
+        tenant_id = claims["tid"]
+        raise AuthenticationError, "Entra inbound token is missing tid" if tenant_id.to_s.empty?
+
+        issuers = ["#{@cloud.login_endpoint}/#{tenant_id}/v2.0", "#{ENTRA_V1_ISSUER_PREFIX}#{tenant_id}/"]
+        # Cheap claim checks run first so junk inbound tokens cannot trigger
+        # JWKS fetches for arbitrary tenants; decode! re-verifies both after
+        # the signature.
+        raise AuthenticationError, "JWT issuer is invalid" unless issuers.include?(claims["iss"])
+        raise AuthenticationError, "JWT audience is invalid" if (Array(claims["aud"]) & valid_audiences).empty?
+
+        uri = entra_tenant_jwks_uri(tenant_id)
+        decode!(token, issuers: issuers) do |header, _decoded|
+          signing_key(uri, header["kid"])
+        end
       end
 
       # Inbound tokens may be audienced as the bare app id, api://{appId},
@@ -71,77 +132,121 @@ module Teams
         raise AuthenticationError, "Service URL mismatch. Token: #{normalized_token_url}, Expected: #{normalized_expected_url}"
       end
 
-      def verify_signature!(header, signing_input, signature)
-        raise AuthenticationError, "only RS256 JWTs are supported" unless header["alg"] == "RS256"
+      def signing_key(uri, kid)
+        unless kid.nil? || kid.is_a?(String)
+          raise AuthenticationError, "JWT signing key ID is invalid"
+        end
 
-        key = jwks_for_issuer(signing_input).fetch("keys").find { |candidate| candidate["kid"] == header["kid"] }
-        raise AuthenticationError, "JWT signing key was not found" unless key
+        cached = cached_signing_key(uri, kid)
+        return cached if cached
 
-        public_key = rsa_public_key(key)
-        unless public_key.verify(OpenSSL::Digest.new("SHA256"), signature, signing_input)
-          raise AuthenticationError, "JWT signature is invalid"
+        fetch_mutex = @jwks_mutex.synchronize do
+          mutex = @jwks_fetch_mutexes[uri]
+          unless mutex
+            @jwks_fetch_mutexes.shift while @jwks_fetch_mutexes.length >= MAX_JWKS_ENDPOINTS
+            mutex = @jwks_fetch_mutexes[uri] = Mutex.new
+          end
+          mutex
+        end
+        fetch_mutex.synchronize do
+          cached = cached_signing_key(uri, kid)
+          return cached if cached
+
+          key = fetch_signing_key(uri, kid)
+          @jwks_mutex.synchronize do
+            cache = endpoint_cache(uri)
+            cache.shift if cache.size >= JWKS_CACHE_MAX_ENTRIES
+            cache[kid] = { key:, expires_at: monotonic_time + JWKS_CACHE_TTL }
+          end
+          key
         end
       end
 
-      def jwks_for_issuer(signing_input)
-        _header_segment, payload_segment = signing_input.split(".", 2)
-        payload = JSON.parse(Base64.urlsafe_decode64(pad(payload_segment)))
-        uri = jwks_uri_for_issuer(payload["iss"])
+      def cached_signing_key(uri, kid)
+        @jwks_mutex.synchronize do
+          cache = endpoint_cache(uri)
+          cached = cache.delete(kid)
+          if cached && monotonic_time < cached[:expires_at]
+            cache[kid] = cached
+            cached[:key]
+          end
+        end
+      end
+
+      # Must be called while holding @jwks_mutex.
+      def endpoint_cache(uri)
+        cache = @jwks[uri]
+        unless cache
+          @jwks.shift while @jwks.length >= MAX_JWKS_ENDPOINTS
+          cache = @jwks[uri] = {}
+        end
+        cache
+      end
+
+      def fetch_signing_key(uri, kid)
+        document = @http.get(uri)
+        unless document.is_a?(Hash) && document["keys"].is_a?(Array)
+          raise AuthenticationError, "JWT signing keys response is invalid"
+        end
+
+        keys = document["keys"].select do |key|
+          key.is_a?(Hash) && key["kty"] == "RSA" && [nil, "sig"].include?(key["use"])
+        end
+        if kid.nil? && keys.size != 1
+          raise AuthenticationError, "JWT signing key was not found"
+        end
+        key = kid.nil? ? keys.first : keys.find { |candidate| candidate["kid"] == kid }
+        raise AuthenticationError, "JWT signing key was not found" unless key
 
-        @jwks_mutex.synchronize { @jwks[uri] ||= @http.get(uri) }
-      rescue JSON::ParserError, ArgumentError
-        raise AuthenticationError, "JWT is malformed"
+        unless [key["n"], key["e"]].all? { |value| value.is_a?(String) && !value.empty? }
+          raise AuthenticationError, "JWT signing key is invalid"
+        end
+
+        JWT::JWK.import(key).verify_key
+      rescue HttpError, Faraday::Error, JWT::DecodeError, ArgumentError, OpenSSL::PKey::PKeyError, OpenSSL::ASN1::ASN1Error => error
+        raise AuthenticationError, "Unable to retrieve JWT signing key: #{error.message}"
       end
 
       def jwks_uri_for_issuer(issuer)
-        return bot_framework_jwks_uri if issuer == @cloud.token_issuer
-        return entra_jwks_uri if @tenant_id && tenant_issuer?(issuer)
+        raise AuthenticationError, "JWT issuer is invalid" unless valid_issuers.include?(issuer)
 
-        bot_framework_jwks_uri
+        issuer == @cloud.token_issuer ? bot_framework_jwks_uri : entra_tenant_jwks_uri(@tenant_id)
       end
 
       def bot_framework_jwks_uri
-        @jwks_mutex.synchronize do
+        @discovery_mutex.synchronize do
           @bot_framework_jwks_uri ||= begin
             metadata = @http.get(@cloud.open_id_metadata_url)
-            metadata.fetch("jwks_uri")
+            unless metadata.is_a?(Hash) && metadata["jwks_uri"].is_a?(String) && !metadata["jwks_uri"].empty?
+              raise AuthenticationError, "JWT signing keys metadata is invalid"
+            end
+
+            metadata["jwks_uri"]
           end
         end
+      rescue HttpError, Faraday::Error => error
+        raise AuthenticationError, "Unable to retrieve JWT signing keys metadata: #{error.message}"
       end
 
-      def entra_jwks_uri
-        "#{@cloud.login_endpoint}/#{@tenant_id}/discovery/v2.0/keys"
+      def entra_tenant_jwks_uri(tenant_id)
+        "#{@cloud.login_endpoint}/#{tenant_id}/discovery/v2.0/keys"
       end
 
-      def valid_issuer?(issuer)
-        return true if issuer == @cloud.token_issuer
-        return false unless @tenant_id
-
-        tenant_issuer?(issuer)
-      end
+      def valid_issuers
+        issuers = [@cloud.token_issuer]
+        if @tenant_id
+          issuers.concat(["#{@cloud.login_endpoint}/#{@tenant_id}/v2.0", "#{ENTRA_V1_ISSUER_PREFIX}#{@tenant_id}/"])
+        end
 
-      def tenant_issuer?(issuer)
-        issuer == "#{@cloud.login_endpoint}/#{@tenant_id}/v2.0" ||
-          issuer == "https://sts.windows.net/#{@tenant_id}/"
+        issuers
       end
 
       def normalize_url(value)
         value.to_s.sub(%r{/+\z}, "").downcase
       end
 
-      def rsa_public_key(jwk)
-        n = OpenSSL::BN.new(Base64.urlsafe_decode64(pad(jwk.fetch("n"))), 2)
-        e = OpenSSL::BN.new(Base64.urlsafe_decode64(pad(jwk.fetch("e"))), 2)
-
-        sequence = OpenSSL::ASN1::Sequence([
-          OpenSSL::ASN1::Integer(n),
-          OpenSSL::ASN1::Integer(e)
-        ])
-        OpenSSL::PKey::RSA.new(sequence.to_der)
-      end
-
-      def pad(segment)
-        segment + ("=" * ((4 - segment.length % 4) % 4))
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end
     end
   end

data/lib/teams/auth/token_manager.rb

@@ -5,6 +5,10 @@ require "uri"
 module Teams
   module Auth
     class TokenManager
+      TOKEN_EXCHANGE_SCOPE = "api://AzureADTokenExchange/.default"
+      CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+      JWT_BEARER_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:jwt-bearer"
+
       attr_reader :credentials, :cloud, :http
 
       def initialize(credentials:, cloud: PUBLIC_CLOUD, http: nil)
@@ -63,6 +67,134 @@ module Teams
           access_token
         end
       end
+
+      # Agent 365 tokens use a three-step exchange (the other SDKs delegate
+      # it to MSAL; Ruby implements the grants directly):
+      #   1. client-credentials with fmi_path=<agenticAppId> for the token
+      #      exchange scope - the blueprint assertion.
+      #   2. client-credentials as client_id=<agenticAppId>, authenticated
+      #      by the step-1 assertion - the agentic app token.
+      #   3. the user federated-identity grant (requested_token_use
+      #      on_behalf_of, user_object_id=<agenticUserId>), asserted by a
+      #      step-2 exchange token - the agentic user token.
+      # Steps 1 and 3 reproduce MSAL-internal wire forms from its documented
+      # parameters.
+      # There is deliberately no app-token fallback: failing is safer than
+      # authenticating under the wrong identity, like the other SDKs.
+      def agentic_app_token(scope, agentic_app_id:, tenant_id: nil)
+        tenant = resolve_agentic_tenant!(tenant_id)
+        raise ArgumentError, "agentic_app_id is required for agentic tokens" if agentic_app_id.to_s.empty?
+
+        @mutex.synchronize do
+          cached_token([:agentic_app, scope, agentic_app_id, tenant]) do
+            acquire_agentic_app_token(scope, agentic_app_id, tenant)
+          end
+        end
+      end
+
+      def agentic_user_token(scope, agentic_app_id:, agentic_user_id:, tenant_id: nil)
+        tenant = resolve_agentic_tenant!(tenant_id)
+        raise ArgumentError, "agentic_app_id is required for agentic tokens" if agentic_app_id.to_s.empty?
+        raise ArgumentError, "agentic_user_id is required for agentic user tokens" if agentic_user_id.to_s.empty?
+
+        @mutex.synchronize do
+          cached_token([:agentic_user, scope, agentic_app_id, agentic_user_id, tenant]) do
+            exchange_token = acquire_agentic_app_token(TOKEN_EXCHANGE_SCOPE, agentic_app_id, tenant)
+            response = http.post(
+              token_url(tenant),
+              body: URI.encode_www_form(
+                grant_type: JWT_BEARER_GRANT_TYPE,
+                client_id: agentic_app_id,
+                client_assertion_type: CLIENT_ASSERTION_TYPE,
+                client_assertion: blueprint_assertion(agentic_app_id, tenant),
+                assertion: exchange_token,
+                requested_token_use: "on_behalf_of",
+                user_object_id: agentic_user_id,
+                scope:
+              ),
+              headers: FORM_HEADERS
+            )
+            fetch_access_token!(response, "Agent token exchange step 3 failed")
+          end
+        end
+      end
+
+      private
+
+      FORM_HEADERS = { "Content-Type" => "application/x-www-form-urlencoded" }.freeze
+
+      def token_url(tenant_id)
+        "#{cloud.login_endpoint}/#{tenant_id}/oauth2/v2.0/token"
+      end
+
+      # Agentic tenant resolution is strict: the identity's tenant or the
+      # configured credentials tenant, never the shared login tenant.
+      def resolve_agentic_tenant!(tenant_id)
+        raise ConfigurationError, "CLIENT_ID and CLIENT_SECRET are required" unless credentials
+
+        tenant = tenant_id || credentials.tenant_id
+        raise ArgumentError, "tenant_id is required for agentic tokens" if tenant.to_s.empty?
+
+        tenant
+      end
+
+      def cached_token(key)
+        cached = @tokens[key]
+        return cached.value if cached && !cached.expired?
+
+        token = yield
+        @tokens[key] = Token.new(token)
+        token
+      end
+
+      # Step 1: the blueprint assertion - the app's own client-credentials
+      # grant carrying MSAL's federated-managed-identity path parameter.
+      # Cached like any token so multi-step flows reuse it while valid.
+      def blueprint_assertion(agentic_app_id, tenant_id)
+        cached_token([:blueprint_assertion, agentic_app_id, tenant_id]) do
+          request_blueprint_assertion(agentic_app_id, tenant_id)
+        end
+      end
+
+      def request_blueprint_assertion(agentic_app_id, tenant_id)
+        response = http.post(
+          token_url(tenant_id),
+          body: URI.encode_www_form(
+            grant_type: "client_credentials",
+            client_id: credentials.client_id,
+            client_secret: credentials.client_secret,
+            scope: TOKEN_EXCHANGE_SCOPE,
+            fmi_path: agentic_app_id
+          ),
+          headers: FORM_HEADERS
+        )
+        fetch_access_token!(response, "Agent token exchange step 1 failed")
+      end
+
+      # Step 2: client-credentials as the agentic app, authenticated by the
+      # step-1 assertion instead of a secret.
+      def acquire_agentic_app_token(scope, agentic_app_id, tenant_id)
+        response = http.post(
+          token_url(tenant_id),
+          body: URI.encode_www_form(
+            grant_type: "client_credentials",
+            client_id: agentic_app_id,
+            client_assertion_type: CLIENT_ASSERTION_TYPE,
+            client_assertion: blueprint_assertion(agentic_app_id, tenant_id),
+            scope:
+          ),
+          headers: FORM_HEADERS
+        )
+        fetch_access_token!(response, "Agent token exchange step 2 failed")
+      end
+
+      def fetch_access_token!(response, error_prefix)
+        token = response["access_token"] if response.is_a?(Hash)
+        return token unless token.to_s.empty?
+
+        detail = response.is_a?(Hash) ? response["error_description"] || response["error"] : nil
+        raise Error, "#{error_prefix}: #{detail || "could not acquire token"}"
+      end
     end
   end
 end

data/lib/teams/cloud_environment.rb

@@ -9,6 +9,7 @@ module Teams
     :open_id_metadata_url,
     :token_issuer,
     :graph_scope,
+    :agent_bot_scope,
     keyword_init: true
   )
 
@@ -19,7 +20,10 @@ module Teams
     token_service_url: "https://token.botframework.com",
     open_id_metadata_url: "https://login.botframework.com/v1/.well-known/openidconfiguration",
     token_issuer: "https://api.botframework.com",
-    graph_scope: "https://graph.microsoft.com/.default"
+    graph_scope: "https://graph.microsoft.com/.default",
+    # Agent ID Bot API scope; sovereign-cloud values are unconfirmed
+    # upstream too.
+    agent_bot_scope: "https://botapi.skype.com/.default"
   )
 
   module CloudEnvironments

data/lib/teams/http_stream.rb

@@ -14,9 +14,11 @@ module Teams
 
     attr_reader :app, :conversation_reference
 
-    def initialize(app:, conversation_reference:)
+    def initialize(app:, conversation_reference:, api: nil)
       @app = app
       @conversation_reference = conversation_reference
+      # Scoped to the turn's agentic identity when the app runs as an agent.
+      @api = api || app.api
       @mutex = Mutex.new
       @flusher = nil
       @flushing = false
@@ -363,14 +365,14 @@ module Teams
       # Stream chunks and the streamed final carry a streaminfo entity and are
       # always created; only the timed-out in-place final routes through update.
       if body["id"] && !streaminfo_entity?(body)
-        app.api.conversations.update_activity(
+        @api.conversations.update_activity(
           conversation_reference.conversation_id,
           body["id"],
           body,
           service_url: conversation_reference.service_url
         )
       else
-        app.api.conversations.create_activity(
+        @api.conversations.create_activity(
           conversation_reference.conversation_id,
           body,
           service_url: conversation_reference.service_url

data/lib/teams/router.rb

@@ -96,6 +96,31 @@ module Teams
       register("meeting_end", event_selector("application/vnd.microsoft.meetingEnd"), &block)
     end
 
+    # Agent 365 agentLifecycle events (type "event", name "agentLifecycle"),
+    # discriminated by the activity-level valueType, with the Python method
+    # names. The PascalCase valueType literals are service-owned wire values
+    # shared by all three SDKs.
+    def on_agent_lifecycle(&block)
+      register("agent_lifecycle", agent_lifecycle_selector(nil), &block)
+    end
+
+    AGENT_LIFECYCLE_EVENTS = {
+      "on_agentic_user_identity_created" => "AgenticUserIdentityCreated",
+      "on_agentic_user_identity_updated" => "AgenticUserIdentityUpdated",
+      "on_agentic_user_manager_updated" => "AgenticUserManagerUpdated",
+      "on_agentic_user_enabled" => "AgenticUserEnabled",
+      "on_agentic_user_disabled" => "AgenticUserDisabled",
+      "on_agentic_user_deleted" => "AgenticUserDeleted",
+      "on_agentic_user_undeleted" => "AgenticUserUndeleted",
+      "on_agentic_user_workload_onboarding_updated" => "AgenticUserWorkloadOnboardingUpdated"
+    }.freeze
+
+    AGENT_LIFECYCLE_EVENTS.each do |method_name, value_type|
+      define_method(method_name) do |&block|
+        register(method_name.delete_prefix("on_"), agent_lifecycle_selector(value_type), &block)
+      end
+    end
+
     # conversationUpdate activities and their channel/team lifecycle
     # sub-events, routed by channelData.eventType with the Python method
     # names (the eventType literals are shared by all three SDKs).
@@ -190,6 +215,14 @@ module Teams
       end
     end
 
+    def agent_lifecycle_selector(value_type)
+      lambda do |activity|
+        next false unless activity.type == "event" && activity.name == "agentLifecycle"
+
+        value_type.nil? || activity.value_type == value_type
+      end
+    end
+
     def dialog_selector(invoke_name, key, expected)
       lambda do |activity|
         next false unless activity.invoke? && activity.name == invoke_name

data/lib/teams/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Teams
-  VERSION = "2.0.2"
+  VERSION = "2.0.3"
 end

data/lib/teams.rb

@@ -8,6 +8,7 @@ require_relative "teams/cloud_environment"
 require_relative "teams/cards"
 require_relative "teams/cards/generated"
 require_relative "teams/api/model"
+require_relative "teams/api/agentic_identity"
 require_relative "teams/api/account"
 require_relative "teams/api/conversation_account"
 require_relative "teams/api/conversation_resource"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: teams_rb
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.0.3
 platform: ruby
 authors:
 - Devran Cosmo Uenal
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
@@ -124,6 +138,7 @@ files:
 - docs/getting-started/running-in-teams.md
 - docs/in-depth-guides/README.md
 - docs/in-depth-guides/adaptive-cards.md
+- docs/in-depth-guides/agent-365.md
 - docs/in-depth-guides/dialogs.md
 - docs/in-depth-guides/feedback.md
 - docs/in-depth-guides/meeting-events.md
@@ -138,6 +153,7 @@ files:
 - lib/teams/activity_context.rb
 - lib/teams/api/account.rb
 - lib/teams/api/activity_value.rb
+- lib/teams/api/agentic_identity.rb
 - lib/teams/api/app_info.rb
 - lib/teams/api/bot_sign_in_client.rb
 - lib/teams/api/channel_data.rb
@@ -213,7 +229,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Unofficial Ruby SDK for building Microsoft Teams bots and apps
 test_files: []