teams_rb 2.0.1 → 2.0.3

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/api/conversation_client.rb

@@ -41,7 +41,9 @@ module Teams
       def reply_to_activity(conversation_id, activity_id, activity, service_url: nil)
         body = activity_to_h(activity)
         body = body.merge("replyToId" => activity_id) if body.is_a?(Hash)
-        path = "/v3/conversations/#{escape(conversation_id)}/activities/#{escape(activity_id)}"
+        # Replies POST to the base activities collection; the reply
+        # semantics ride entirely in the body's replyToId.
+        path = "/v3/conversations/#{escape(conversation_id)}/activities"
         url = absolute(path, service_url:)
         @logger&.debug("Teams API POST #{url}")
         http.post(url, json: body)

data/lib/teams/api/message_activity.rb

@@ -3,6 +3,7 @@
 module Teams
   module Api
     class MessageActivity
+      # "extendedmarkdown" is in public preview and may be subject to change.
       TEXT_FORMATS = %w[plain markdown xml extendedmarkdown].freeze
       FEEDBACK_MODES = %w[default custom].freeze
       AI_MESSAGE_ENTITY_TYPE = "https://schema.org/Message"

data/lib/teams/api/search.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Teams
+  module Api
+    # A single application/search result: title is the display text, value
+    # is submitted when the user selects it.
+    class SearchInvokeResult
+      def initialize(title:, value:)
+        @title = title
+        @value = value
+      end
+
+      def to_h
+        { "title" => @title, "value" => @value }
+      end
+    end
+
+    # Response body for application/search invokes (Adaptive Card dynamic
+    # typeahead Input.ChoiceSet queries). results accepts SearchInvokeResult
+    # objects or {title:, value:} hashes.
+    class SearchResponse
+      def initialize(results, status_code: 200)
+        @results = results
+        @status_code = status_code
+      end
+
+      def to_h
+        {
+          "statusCode" => @status_code,
+          "type" => "application/vnd.microsoft.search.searchResponse",
+          "value" => {
+            "results" => Array(@results).map do |result|
+              body = result.is_a?(Hash) ? result : result.to_h
+              Common::Hashes.deep_stringify_keys(body)
+            end
+          }
+        }
+      end
+    end
+  end
+end

data/lib/teams/app.rb

@@ -5,6 +5,10 @@ require "logger"
 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
 
     attr_reader :api, :logger, :storage, :messaging_endpoint, :default_connection_name, :graph
 
@@ -22,7 +26,8 @@ module Teams
       storage: Storage::MemoryStore.new,
       api: nil,
       token_manager: nil,
-      skip_auth: false,
+      dangerously_allow_unauthenticated_requests: nil,
+      skip_auth: nil,
       messaging_endpoint: DEFAULT_MESSAGING_ENDPOINT,
       default_connection_name: "graph"
     )
@@ -33,7 +38,9 @@ module Teams
       @logger = logger
       @storage = storage
       @cloud = cloud
-      @skip_auth = skip_auth
+      @dangerously_allow_unauthenticated_requests = resolve_unauthenticated_requests_option(
+        dangerously_allow_unauthenticated_requests, skip_auth
+      )
       @messaging_endpoint = normalize_messaging_endpoint(messaging_endpoint)
       @router = Router.new
 
@@ -42,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,
@@ -140,6 +148,14 @@ module Teams
       self
     end
 
+    # application/search invokes from Adaptive Card dynamic typeahead
+    # Input.ChoiceSet queries; the handler's return (Api::SearchResponse or
+    # hash) becomes the invoke response body.
+    def on_card_search(&block)
+      @router.on_card_search(&block)
+      self
+    end
+
     # Called with (ctx, token_response) whenever a sign-in completes through
     # the default token-exchange or verify-state handlers.
     def on_sign_in(&block)
@@ -206,6 +222,36 @@ module Teams
       self
     end
 
+    # conversationUpdate activities plus their channel/team lifecycle
+    # sub-events (on_channel_created, on_team_renamed, ...), routed by
+    # channelData.eventType with the Python method names.
+    def on_conversation_update(&block)
+      @router.on_conversation_update(&block)
+      self
+    end
+
+    Router::CONVERSATION_UPDATE_EVENTS.each_key do |method_name|
+      define_method(method_name) do |&block|
+        @router.public_send(method_name, &block)
+        self
+      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
@@ -237,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
@@ -254,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
@@ -277,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)
 
@@ -326,7 +392,8 @@ module Teams
     # ending in ctx.post must not leak the SentActivity into the response.
     def invoke_response_body(result)
       case result
-      when Api::TaskModuleResponse, Api::MessagingExtensionResponse, Api::MessagingExtensionActionResponse
+      when Api::TaskModuleResponse, Api::MessagingExtensionResponse, Api::MessagingExtensionActionResponse,
+           Api::SearchResponse
         result.to_h
       when Hash
         Common::Hashes.deep_stringify_keys(result)
@@ -396,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
@@ -437,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"]
@@ -487,32 +602,80 @@ module Teams
       end
     end
 
+    # Resolves the auth-bypass setting like the Python SDK: the explicit
+    # option wins, then the deprecated skip_auth alias, then the env var,
+    # defaulting to false. Passing skip_auth always warns, even when the
+    # new option overrides it.
+    def resolve_unauthenticated_requests_option(explicit, skip_auth)
+      unless skip_auth.nil?
+        warn("skip_auth is deprecated; use dangerously_allow_unauthenticated_requests instead.", uplevel: 2)
+      end
+      return explicit unless explicit.nil?
+      return skip_auth unless skip_auth.nil?
+
+      parse_bool_env_var(DANGEROUSLY_ALLOW_UNAUTHENTICATED_REQUESTS_ENV_VAR) || false
+    end
+
+    def parse_bool_env_var(name)
+      value = ENV[name].to_s.strip.downcase
+      return nil if value.empty?
+      return true if TRUE_ENV_VALUES.include?(value)
+      return false if FALSE_ENV_VALUES.include?(value)
+
+      raise ArgumentError, "#{name} must be a boolean value: true/false, 1/0, yes/no, or on/off."
+    end
+
     # The same two startup warnings the TypeScript, Python, and .NET SDKs
     # log when no credentials are configured. Settled 2026-07-12: exact
-    # upstream branches only; credentials-plus-skip_auth stays silent like
+    # upstream branches only; credentials-plus-bypass stays silent like
     # the other SDKs.
     def warn_missing_credentials
       return if @token_manager.client_id
 
-      if @skip_auth
+      if @dangerously_allow_unauthenticated_requests
         logger&.warn(
           "No credentials configured (CLIENT_ID / CLIENT_SECRET / TENANT_ID), " \
-          "but skip_auth is enabled. Bot will accept unauthenticated requests on #{@messaging_endpoint}."
+          "but dangerously_allow_unauthenticated_requests is enabled. " \
+          "Bot will accept unauthenticated requests on #{@messaging_endpoint}."
         )
       else
         logger&.warn(
-          "No credentials configured and skip_auth is not enabled. All incoming requests will be rejected. " \
-          "Configure client authentication to securely receive messages, or set skip_auth: true for local development."
+          "No credentials configured and dangerously_allow_unauthenticated_requests is not enabled. " \
+          "All incoming requests will be rejected. Configure client authentication to securely receive " \
+          "messages, or set dangerously_allow_unauthenticated_requests: true for local development."
+        )
+      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 @skip_auth
+      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)