teams_rb 2.0.1 → 2.0.3

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
@@ -356,18 +358,21 @@ module Teams
       body = activity.dup
       body["from"] = conversation_reference.bot.to_h if conversation_reference.bot
       body["conversation"] = conversation_reference.conversation.to_h
+      # Every streamed activity replies to the inbound message, restoring
+      # Bot Framework v1 threading behavior.
+      body["replyToId"] = conversation_reference.activity_id if conversation_reference.activity_id
 
       # 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

@@ -72,6 +72,12 @@ module Teams
       register("message.submit", invoke_selector("message/submitAction"), &block)
     end
 
+    # application/search invokes - Adaptive Card dynamic typeahead
+    # Input.ChoiceSet queries (choices.data / Data.Query).
+    def on_card_search(&block)
+      register("card.search", invoke_selector("application/search"), &block)
+    end
+
     # message/submitAction invokes whose actionName is "feedback" - the
     # submissions from add_feedback's thumbs up/down UI.
     def on_message_submit_feedback(&block)
@@ -90,6 +96,57 @@ 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).
+    def on_conversation_update(&block)
+      register("conversation_update", ->(activity) { activity.type == "conversationUpdate" }, &block)
+    end
+
+    CONVERSATION_UPDATE_EVENTS = {
+      "on_channel_created" => "channelCreated",
+      "on_channel_deleted" => "channelDeleted",
+      "on_channel_renamed" => "channelRenamed",
+      "on_channel_restored" => "channelRestored",
+      "on_team_archived" => "teamArchived",
+      "on_team_deleted" => "teamDeleted",
+      "on_team_hard_deleted" => "teamHardDeleted",
+      "on_team_renamed" => "teamRenamed",
+      "on_team_restored" => "teamRestored",
+      "on_team_unarchived" => "teamUnarchived"
+    }.freeze
+
+    CONVERSATION_UPDATE_EVENTS.each do |method_name, event_type|
+      define_method(method_name) do |&block|
+        register(event_type, conversation_update_selector(event_type), &block)
+      end
+    end
+
     # Message extension (compose extension) invoke routes, using the same
     # route names as the TypeScript and Python SDKs.
     MESSAGE_EXTENSION_ROUTES = {
@@ -152,6 +209,20 @@ module Teams
       ->(activity) { activity.type == "event" && activity.name == event_name }
     end
 
+    def conversation_update_selector(event_type)
+      lambda do |activity|
+        activity.type == "conversationUpdate" && activity.channel_data.event_type == event_type
+      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.1"
+  VERSION = "2.0.3"
 end

data/lib/teams.rb

@@ -8,10 +8,12 @@ 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"
 require_relative "teams/api/paged_members_result"
+require_relative "teams/api/app_info"
 require_relative "teams/api/tenant_info"
 require_relative "teams/api/team_info"
 require_relative "teams/api/team_details"
@@ -27,6 +29,7 @@ require_relative "teams/api/sent_activity"
 require_relative "teams/api/citation_appearance"
 require_relative "teams/api/task_module"
 require_relative "teams/api/message_extension"
+require_relative "teams/api/search"
 require_relative "teams/activity"
 require_relative "teams/activity_context"
 require_relative "teams/function_context"