@microsoft/agents-hosting 1.1.0-alpha.5 → 1.1.0-alpha.58

package/src/app/agentApplication.ts

@@ -12,7 +12,6 @@ import { AdaptiveCardsActions } from './adaptiveCards'
 import { AgentApplicationOptions } from './agentApplicationOptions'
 import { ConversationUpdateEvents } from './conversationUpdateEvents'
 import { AgentExtension } from './extensions'
-import { Authorization, SignInState } from './authorization'
 import { RouteHandler } from './routeHandler'
 import { RouteSelector } from './routeSelector'
 import { TurnEvents } from './turnEvents'
@@ -21,6 +20,8 @@ import { RouteRank } from './routeRank'
 import { RouteList } from './routeList'
 import { TranscriptLoggerMiddleware } from '../transcript'
 import { CloudAdapter } from '../cloudAdapter'
+import { Authorization, AuthorizationManager } from './auth'
+import { JwtPayload } from 'jsonwebtoken'
 
 const logger = debug('agents:app')
 
@@ -74,6 +75,7 @@ export class AgentApplication<TState extends TurnState> {
   protected readonly _beforeTurn: ApplicationEventHandler<TState>[] = []
   protected readonly _afterTurn: ApplicationEventHandler<TState>[] = []
   private readonly _adapter?: CloudAdapter
+  private readonly _authorizationManager?: AuthorizationManager
   private readonly _authorization?: Authorization
   private _typingTimer: NodeJS.Timeout | undefined
   protected readonly _extensions: AgentExtension<TState>[] = []
@@ -125,7 +127,8 @@ export class AgentApplication<TState extends TurnState> {
     }
 
     if (this._options.authorization) {
-      this._authorization = new Authorization(this._options.storage!, this._options.authorization, this._adapter?.userTokenClient!)
+      this._authorizationManager = new AuthorizationManager(this, this._adapter.connectionManager)
+      this._authorization = new Authorization(this._authorizationManager)
     }
 
     if (this._options.longRunningMessages && !this._adapter && !this._options.agentAppId) {
@@ -227,6 +230,7 @@ export class AgentApplication<TState extends TurnState> {
    * @param isInvokeRoute - Whether this route is for invoke activities. Defaults to false.
    * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
    * @param authHandlers - Array of authentication handler names for this route. Defaults to empty array.
+   * @param isAgenticRoute - Whether this route is for agentic requests only. Defaults to false.
    * @returns The current instance of the application.
    *
    * @remarks
@@ -247,8 +251,8 @@ export class AgentApplication<TState extends TurnState> {
    * ```
    *
    */
-  public addRoute (selector: RouteSelector, handler: RouteHandler<TState>, isInvokeRoute: boolean = false, rank: number = RouteRank.Unspecified, authHandlers: string[] = []): this {
-    this._routes.addRoute(selector, handler, isInvokeRoute, rank, authHandlers)
+  public addRoute (selector: RouteSelector, handler: RouteHandler<TState>, isInvokeRoute: boolean = false, rank: number = RouteRank.Unspecified, authHandlers: string[] = [], isAgenticRoute: boolean = false): this {
+    this._routes.addRoute(selector, handler, isInvokeRoute, rank, authHandlers, isAgenticRoute)
     return this
   }
 
@@ -259,6 +263,7 @@ export class AgentApplication<TState extends TurnState> {
    * @param handler - The handler function that will be called when the specified activity type is received.
    * @param authHandlers - Array of authentication handler names for this activity. Defaults to empty array.
    * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
+   * @param isAgenticRoute - Indicates if this handler is for agentic requests only. Defaults to false.
    * @returns The current instance of the application.
    *
    * @remarks
@@ -277,11 +282,12 @@ export class AgentApplication<TState extends TurnState> {
     type: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[],
     handler: (context: TurnContext, state: TState) => Promise<void>,
     authHandlers: string[] = [],
-    rank: RouteRank = RouteRank.Unspecified
+    rank: RouteRank = RouteRank.Unspecified,
+    isAgenticRoute: boolean = false
   ): this {
     (Array.isArray(type) ? type : [type]).forEach((t) => {
-      const selector = this.createActivitySelector(t)
-      this.addRoute(selector, handler, false, rank, authHandlers)
+      const selector = this.createActivitySelector(t, isAgenticRoute)
+      this.addRoute(selector, handler, false, rank, authHandlers, isAgenticRoute)
     })
     return this
   }
@@ -293,6 +299,7 @@ export class AgentApplication<TState extends TurnState> {
    * @param handler - The handler function that will be called when the specified event occurs.
    * @param authHandlers - Array of authentication handler names for this event. Defaults to empty array.
    * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
+   * @param isAgenticRoute - Indicates if this handler is for agentic requests only. Defaults to false.
    * @returns The current instance of the application.
    * @throws Error if the handler is not a function.
    *
@@ -316,7 +323,8 @@ export class AgentApplication<TState extends TurnState> {
     event: ConversationUpdateEvents,
     handler: (context: TurnContext, state: TState) => Promise<void>,
     authHandlers: string[] = [],
-    rank: RouteRank = RouteRank.Unspecified
+    rank: RouteRank = RouteRank.Unspecified,
+    isAgenticRoute: boolean = false
   ): this {
     if (typeof handler !== 'function') {
       throw new Error(
@@ -324,8 +332,8 @@ export class AgentApplication<TState extends TurnState> {
       )
     }
 
-    const selector = this.createConversationUpdateSelector(event)
-    this.addRoute(selector, handler, false, rank, authHandlers)
+    const selector = this.createConversationUpdateSelector(event, isAgenticRoute)
+    this.addRoute(selector, handler, false, rank, authHandlers, isAgenticRoute)
     return this
   }
 
@@ -338,6 +346,7 @@ export class AgentApplication<TState extends TurnState> {
    * @throws Error if the adapter is not configured.
    */
   protected async continueConversationAsync (
+    botAppIdOrIdentity: string | JwtPayload,
     conversationReferenceOrContext: ConversationReference | TurnContext,
     logic: (context: TurnContext) => Promise<void>
   ): Promise<void> {
@@ -359,7 +368,7 @@ export class AgentApplication<TState extends TurnState> {
       reference = conversationReferenceOrContext
     }
 
-    await this._adapter.continueConversation(reference, logic)
+    await this._adapter.continueConversation(botAppIdOrIdentity, reference, logic)
   }
 
   /**
@@ -370,6 +379,7 @@ export class AgentApplication<TState extends TurnState> {
    * @param handler - The handler function that will be called when a matching message is received.
    * @param authHandlers - Array of authentication handler names for this message handler. Defaults to empty array.
    * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
+   * @param isAgenticRoute - Indicates if this handler is for agentic requests only. Defaults to false.
    * @returns The current instance of the application.
    *
    * @remarks
@@ -394,11 +404,12 @@ export class AgentApplication<TState extends TurnState> {
     keyword: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[],
     handler: (context: TurnContext, state: TState) => Promise<void>,
     authHandlers: string[] = [],
-    rank: RouteRank = RouteRank.Unspecified
+    rank: RouteRank = RouteRank.Unspecified,
+    isAgenticRoute: boolean = false
   ): this {
     (Array.isArray(keyword) ? keyword : [keyword]).forEach((k) => {
-      const selector = this.createMessageSelector(k)
-      this.addRoute(selector, handler, false, rank, authHandlers)
+      const selector = this.createMessageSelector(k, isAgenticRoute)
+      this.addRoute(selector, handler, false, rank, authHandlers, isAgenticRoute)
     })
     return this
   }
@@ -468,6 +479,7 @@ export class AgentApplication<TState extends TurnState> {
    *
    * @param handler - The handler function that will be called when a message reaction is added.
    * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
+   * @param isAgenticRoute - Indicates if this handler is for agentic requests only. Defaults to false.
    * @returns The current instance of the application.
    *
    * @remarks
@@ -487,14 +499,16 @@ export class AgentApplication<TState extends TurnState> {
    */
   public onMessageReactionAdded (
     handler: (context: TurnContext, state: TState) => Promise<void>,
-    rank: RouteRank = RouteRank.Unspecified): this {
+    rank: RouteRank = RouteRank.Unspecified,
+    isAgenticRoute: boolean = false): this {
     const selector = async (context: TurnContext): Promise<boolean> => {
       return context.activity.type === ActivityTypes.MessageReaction &&
              Array.isArray(context.activity.reactionsAdded) &&
-             context.activity.reactionsAdded.length > 0
+             context.activity.reactionsAdded.length > 0 &&
+             (!isAgenticRoute || (isAgenticRoute && context.activity.isAgenticRequest()))
     }
 
-    this.addRoute(selector, handler, false, rank)
+    this.addRoute(selector, handler, false, rank, [], isAgenticRoute)
     return this
   }
 
@@ -503,6 +517,7 @@ export class AgentApplication<TState extends TurnState> {
    *
    * @param handler - The handler function that will be called when a message reaction is removed.
    * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
+   * @param isAgenticRoute - Indicates if this handler is for agentic requests only. Defaults to false.
    * @returns The current instance of the application.
    *
    * @remarks
@@ -522,14 +537,16 @@ export class AgentApplication<TState extends TurnState> {
    */
   public onMessageReactionRemoved (
     handler: (context: TurnContext, state: TState) => Promise<void>,
-    rank: RouteRank = RouteRank.Unspecified): this {
+    rank: RouteRank = RouteRank.Unspecified,
+    isAgenticRoute: boolean = false): this {
     const selector = async (context: TurnContext): Promise<boolean> => {
       return context.activity.type === ActivityTypes.MessageReaction &&
              Array.isArray(context.activity.reactionsRemoved) &&
-             context.activity.reactionsRemoved.length > 0
+             context.activity.reactionsRemoved.length > 0 &&
+             (!isAgenticRoute || (isAgenticRoute && context.activity.isAgenticRequest()))
     }
 
-    this.addRoute(selector, handler, false, rank)
+    this.addRoute(selector, handler, false, rank, undefined, isAgenticRoute)
     return this
   }
 
@@ -571,8 +588,8 @@ export class AgentApplication<TState extends TurnState> {
    * 2. Processes mentions if configured
    * 3. Loads turn state
    * 4. Handles authentication flows
-   * 5. Executes before-turn event handlers
-   * 6. Downloads files if file downloaders are configured
+   * 5. Downloads files if file downloaders are configured
+   * 6. Executes before-turn event handlers
    * 7. Routes to appropriate handlers
    * 8. Executes after-turn event handlers
    * 9. Saves turn state
@@ -587,6 +604,10 @@ export class AgentApplication<TState extends TurnState> {
    *
    */
   public async runInternal (turnContext: TurnContext): Promise<boolean> {
+    if (turnContext.activity.type === ActivityTypes.Typing) {
+      return false
+    }
+
     logger.info('Running application with activity:', turnContext.activity.id!)
     return await this.startLongRunningCall(turnContext, async (context) => {
       try {
@@ -606,27 +627,22 @@ export class AgentApplication<TState extends TurnState> {
         const state = turnStateFactory()
         await state.load(context, storage)
 
-        const signInState : SignInState = state.getValue('user.__SIGNIN_STATE_')
-        logger.debug('SignIn State:', signInState)
-        if (this._authorization && signInState && signInState.completed === false) {
-          const flowState = await this._authorization.authHandlers[signInState.handlerId!]?.flow?.getFlowState(context)
-          logger.debug('Flow State:', flowState)
-          if (flowState && flowState.flowStarted === true) {
-            const tokenResponse = await this._authorization.beginOrContinueFlow(turnContext, state, signInState?.handlerId!)
-            const savedAct = Activity.fromObject(signInState?.continuationActivity!)
-            if (tokenResponse?.token && tokenResponse.token.length > 0) {
-              logger.info('resending continuation activity:', savedAct.text)
-              await this.run(new TurnContext(context.adapter, savedAct))
-              await state.deleteValue('user.__SIGNIN_STATE_')
-              return true
-            }
-          }
+        const { authorized } = await this._authorizationManager?.process(context, async activity => {
+          // The incoming activity may come from the storage, so we need to restore the auth handlers.
+          // Since the current route may not have auth handlers.
+          const route = await this.getRoute(new TurnContext(context.adapter, activity, turnContext.identity))
+          return route?.authHandlers ?? []
+        }) ?? { authorized: true } // Default to authorized if no auth manager
 
-          // return true
+        if (!authorized) {
+          await state.save(context, storage)
+          return false
         }
 
-        if (!(await this.callEventHandlers(context, state, this._beforeTurn))) {
-          await state.save(context, storage)
+        const route = await this.getRoute(context)
+
+        if (!route) {
+          logger.debug('No matching route found for activity:', context.activity)
           return false
         }
 
@@ -636,38 +652,18 @@ export class AgentApplication<TState extends TurnState> {
           }
         }
 
-        for (const route of this._routes) {
-          if (await route.selector(context)) {
-            if (route.authHandlers === undefined || route.authHandlers.length === 0) {
-              await route.handler(context, state)
-            } else {
-              let signInComplete = false
-              for (const authHandlerId of route.authHandlers) {
-                logger.info(`Executing route handler for authHandlerId: ${authHandlerId}`)
-                const tokenResponse = await this._authorization?.beginOrContinueFlow(turnContext, state, authHandlerId)
-                signInComplete = (tokenResponse?.token !== undefined && tokenResponse?.token.length > 0)
-                if (!signInComplete) {
-                  break
-                }
-              }
-              if (signInComplete) {
-                await route.handler(context, state)
-              }
-            }
-
-            if (await this.callEventHandlers(context, state, this._afterTurn)) {
-              await state.save(context, storage)
-            }
-
-            return true
-          }
+        if (!(await this.callEventHandlers(context, state, this._beforeTurn))) {
+          await state.save(context, storage)
+          return false
         }
 
+        await route.handler(context, state)
+
         if (await this.callEventHandlers(context, state, this._afterTurn)) {
           await state.save(context, storage)
         }
 
-        return false
+        return true
       } catch (err: any) {
         logger.error(err)
         throw err
@@ -677,6 +673,17 @@ export class AgentApplication<TState extends TurnState> {
     })
   }
 
+  /**
+   * Finds the appropriate route for the given context.
+   */
+  private async getRoute (context: TurnContext) {
+    for (const route of this._routes) {
+      if (await route.selector(context)) {
+        return route
+      }
+    }
+  }
+
   /**
    * Sends a proactive message to a conversation.
    *
@@ -700,13 +707,14 @@ export class AgentApplication<TState extends TurnState> {
    *
    */
   public async sendProactiveActivity (
+    botAppIdOrIdentity: string | JwtPayload,
     context: TurnContext | ConversationReference,
     activityOrText: string | Activity,
     speak?: string,
     inputHint?: string
   ): Promise<ResourceResponse | undefined> {
     let response: ResourceResponse | undefined
-    await this.continueConversationAsync(context, async (ctx) => {
+    await this.continueConversationAsync(botAppIdOrIdentity, context, async (ctx) => {
       response = await ctx.sendActivity(activityOrText, speak, inputHint)
     })
 
@@ -905,7 +913,7 @@ export class AgentApplication<TState extends TurnState> {
   ): Promise<boolean> {
     if (context.activity.type === ActivityTypes.Message && this._options.longRunningMessages) {
       return new Promise<boolean>((resolve, reject) => {
-        this.continueConversationAsync(context, async (ctx) => {
+        this.continueConversationAsync(context.identity, context, async (ctx) => {
           try {
             for (const key in context.activity) {
               (ctx.activity as any)[key] = (context.activity as any)[key]
@@ -928,20 +936,25 @@ export class AgentApplication<TState extends TurnState> {
    * Creates a selector function for activity types.
    *
    * @param type - The activity type to match. Can be a string, RegExp, or RouteSelector function.
+   * @param isAgenticRoute - Indicates if the route is for agentic requests only. Defaults to false.
    * @returns A RouteSelector function that matches the specified activity type.
    */
-  private createActivitySelector (type: string | RegExp | RouteSelector): RouteSelector {
+  private createActivitySelector (type: string | RegExp | RouteSelector, isAgenticRoute: boolean = false): RouteSelector {
     if (typeof type === 'function') {
       return type
     } else if (type instanceof RegExp) {
       return (context: TurnContext) => {
-        return Promise.resolve(context?.activity?.type ? type.test(context.activity.type) : false)
+        return Promise.resolve(context?.activity?.type
+          ? type.test(context.activity.type) && (!isAgenticRoute || (isAgenticRoute && context.activity.isAgenticRequest()))
+          : false)
       }
     } else {
       const typeName = type.toString().toLocaleLowerCase()
       return (context: TurnContext) => {
         return Promise.resolve(
-          context?.activity?.type ? context.activity.type.toLocaleLowerCase() === typeName : false
+          context?.activity?.type
+            ? context.activity.type.toLocaleLowerCase() === typeName && (!isAgenticRoute || (isAgenticRoute && context.activity.isAgenticRequest()))
+            : false
         )
       }
     }
@@ -951,13 +964,15 @@ export class AgentApplication<TState extends TurnState> {
    * Creates a selector function for conversation update events.
    *
    * @param event - The conversation update event to match.
+   * @param isAgenticRoute - Indicates if the route is for agentic requests only. Defaults to false.
    * @returns A RouteSelector function that matches the specified conversation update event.
    */
-  private createConversationUpdateSelector (event: ConversationUpdateEvents): RouteSelector {
+  private createConversationUpdateSelector (event: ConversationUpdateEvents, isAgenticRoute: boolean = false): RouteSelector {
     switch (event) {
       case 'membersAdded':
         return (context: TurnContext): Promise<boolean> => {
           return Promise.resolve(
+            (!isAgenticRoute || (isAgenticRoute && context.activity.isAgenticRequest())) &&
             context?.activity?.type === ActivityTypes.ConversationUpdate &&
                           Array.isArray(context?.activity?.membersAdded) &&
                           context.activity.membersAdded.length > 0
@@ -966,6 +981,7 @@ export class AgentApplication<TState extends TurnState> {
       case 'membersRemoved':
         return (context: TurnContext): Promise<boolean> => {
           return Promise.resolve(
+            (!isAgenticRoute || (isAgenticRoute && context.activity.isAgenticRequest())) &&
             context?.activity?.type === ActivityTypes.ConversationUpdate &&
                           Array.isArray(context?.activity?.membersRemoved) &&
                           context.activity.membersRemoved.length > 0
@@ -974,6 +990,7 @@ export class AgentApplication<TState extends TurnState> {
       default:
         return (context: TurnContext): Promise<boolean> => {
           return Promise.resolve(
+            (!isAgenticRoute || (isAgenticRoute && context.activity.isAgenticRequest())) &&
             context?.activity?.type === ActivityTypes.ConversationUpdate &&
                           context?.activity?.channelData?.eventType === event
           )
@@ -985,14 +1002,17 @@ export class AgentApplication<TState extends TurnState> {
    * Creates a selector function for message content matching.
    *
    * @param keyword - The keyword, pattern, or selector function to match against message text.
+   * @param isAgenticRoute - Indicates if the route is for agentic requests only. Defaults to false.
    * @returns A RouteSelector function that matches messages based on the specified keyword.
    */
-  private createMessageSelector (keyword: string | RegExp | RouteSelector): RouteSelector {
+  private createMessageSelector (keyword: string | RegExp | RouteSelector, isAgenticRoute: boolean = false): RouteSelector {
     if (typeof keyword === 'function') {
       return keyword
     } else if (keyword instanceof RegExp) {
       return (context: TurnContext) => {
-        if (context?.activity?.type === ActivityTypes.Message && context.activity.text) {
+        if (context?.activity?.type === ActivityTypes.Message &&
+          context.activity.text &&
+          (!isAgenticRoute || (isAgenticRoute && context.activity.isAgenticRequest()))) {
           return Promise.resolve(keyword.test(context.activity.text))
         } else {
           return Promise.resolve(false)
@@ -1001,7 +1021,9 @@ export class AgentApplication<TState extends TurnState> {
     } else {
       const k = keyword.toString().toLocaleLowerCase()
       return (context: TurnContext) => {
-        if (context?.activity?.type === ActivityTypes.Message && context.activity.text) {
+        if (context?.activity?.type === ActivityTypes.Message &&
+          context.activity.text &&
+        (!isAgenticRoute || (isAgenticRoute && context.activity.isAgenticRequest()))) {
           return Promise.resolve(context.activity.text.toLocaleLowerCase() === k)
         } else {
           return Promise.resolve(false)

package/src/app/agentApplicationBuilder.ts

@@ -6,7 +6,7 @@
 import { Storage } from '../storage'
 import { AgentApplication } from './agentApplication'
 import { AgentApplicationOptions } from './agentApplicationOptions'
-import { AuthorizationHandlers } from './authorization'
+import { AuthorizationOptions } from './auth/types'
 import { TurnState } from './turnState'
 
 /**
@@ -59,7 +59,7 @@ export class AgentApplicationBuilder<TState extends TurnState = TurnState> {
    * @param authHandlers The user identity authentication options
    * @returns This builder instance for chaining
    */
-  public withAuthorization (authHandlers: AuthorizationHandlers): this {
+  public withAuthorization (authHandlers: AuthorizationOptions): this {
     this._options.authorization = authHandlers
     return this
   }

package/src/app/agentApplicationOptions.ts

@@ -8,9 +8,10 @@ import { Storage } from '../storage'
 import { TranscriptLogger } from '../transcript'
 import { AdaptiveCardsOptions } from './adaptiveCards'
 import { InputFileDownloader } from './inputFileDownloader'
-import { AuthorizationHandlers } from './authorization'
 import { TurnState } from './turnState'
 import { HeaderPropagationDefinition } from '../headerPropagation'
+import { AuthorizationOptions } from './auth/types'
+import { Connections } from '../auth/connections'
 
 /**
  * Configuration options for creating and initializing an Agent Application.
@@ -95,7 +96,7 @@ export interface AgentApplicationOptions<TState extends TurnState> {
    *
    * @default undefined (no authorization required)
    */
-  authorization?: AuthorizationHandlers;
+  authorization?: AuthorizationOptions;
 
   /**
    * Configuration options for handling Adaptive Card actions and interactions.
@@ -139,4 +140,11 @@ export interface AgentApplicationOptions<TState extends TurnState> {
    * @default undefined
    */
   headerPropagation?: HeaderPropagationDefinition
+
+  /**
+   * Optional. Configuration for managing multiple authentication connections within the agent.
+   * This allows the agent to handle authentication across different services or
+   * identity providers.
+   */
+  connections?: Connections
 }

package/src/app/appRoute.ts

@@ -51,6 +51,14 @@ export interface AppRoute<TState extends TurnState> {
    */
   handler: RouteHandler<TState>;
 
+  /**
+   * Indicates whether this route is an agentic-only route.
+   *
+   * @default false
+   *
+   */
+  isAgenticRoute?: boolean;
+
   /**
    * Indicates whether this route is an invoke route.
    *