@microsoft/agents-hosting 0.6.1 → 0.6.11

package/src/app/extensions.ts

@@ -1,19 +1,62 @@
 import { TurnContext } from '../turnContext'
 import { AgentApplication } from './agentApplication'
 import { RouteHandler } from './routeHandler'
+import { RouteRank } from './routeRank'
 import { RouteSelector } from './routeSelector'
 import { TurnState } from './turnState'
 
+/**
+ * Represents an extension that adds channel-specific routing functionality to an agent application.
+ * This class allows you to register routes that are only active for a specific channel.
+ *
+ * @template TState - The type of turn state that extends TurnState
+ */
 export class AgentExtension<TState extends TurnState> {
+  /** The channel ID that this extension is associated with */
   channelId: string
+
+  /**
+   * Creates a new AgentExtension instance for the specified channel.
+   *
+   * @param channelId - The channel ID that this extension will be associated with
+   */
   constructor (channelId: string) {
     this.channelId = channelId
   }
 
-  addRoute (app: AgentApplication<TState>, routeSelector: RouteSelector, routeHandler: RouteHandler<TurnState>, isInvokeRoute: boolean = false) {
+  /**
+   * Adds a route to the agent application that is only active for the channel specified in this extension.
+   * This method creates a channel-specific route by wrapping the provided route selector with an additional
+   * check to ensure the incoming activity matches the extension's channel ID.
+   *
+   * @param app - The agent application instance to add the route to
+   * @param routeSelector - A function that determines if the route should handle the incoming activity
+   * @param routeHandler - The handler function that will process the activity when the route is matched
+   * @param isInvokeRoute - Optional. Whether this route handles invoke activities. Defaults to false
+   * @param rank - Optional. The priority rank of this route for routing precedence. Defaults to RouteRank.Unspecified
+   *
+   * @example
+   * ```typescript
+   * const teamsExtension = new AgentExtension<MyState>('msteams');
+   * teamsExtension.addRoute(
+   *   app,
+   *   (context) => context.activity.type === 'message',
+   *   async (context, state) => {
+   *     // Handle Teams-specific message
+   *     await context.sendActivity('Hello from Teams!');
+   *   }
+   * );
+   * ```
+   */
+  addRoute (
+    app: AgentApplication<TState>,
+    routeSelector: RouteSelector,
+    routeHandler: RouteHandler<TurnState>,
+    isInvokeRoute: boolean = false,
+    rank: number = RouteRank.Unspecified) {
     const ensureChannelMatches = async (context: TurnContext) => {
       return context.activity.channelId === this.channelId && routeSelector(context)
     }
-    app.addRoute(ensureChannelMatches, routeHandler)
+    app.addRoute(ensureChannelMatches, routeHandler, isInvokeRoute, rank)
   }
 }

package/src/app/index.ts

@@ -6,6 +6,8 @@ export * from './attachmentDownloader'
 export * from './authorization'
 export * from './conversationUpdateEvents'
 export * from './routeHandler'
+export * from './routeList'
+export * from './routeRank'
 export * from './routeSelector'
 export * from './turnState'
 export * from './turnEvents'

package/src/app/routeList.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AppRoute } from './appRoute'
+import { RouteHandler } from './routeHandler'
+import { RouteRank } from './routeRank'
+import { RouteSelector } from './routeSelector'
+import { TurnState } from './turnState'
+
+export class RouteList<TState extends TurnState> {
+  private _routes: Array<AppRoute<TState>> = []
+
+  public addRoute (
+    selector: RouteSelector,
+    handler: RouteHandler<TState>,
+    isInvokeRoute: boolean = false,
+    rank: number = RouteRank.Unspecified,
+    authHandlers: string[] = []
+  ): this {
+    this._routes.push({ selector, handler, isInvokeRoute, rank, authHandlers })
+
+    // Invoke selectors are first, then order by rank ascending
+    this._routes.sort((a, b) => {
+      if (a.isInvokeRoute !== b.isInvokeRoute) {
+        return a.isInvokeRoute ? -1 : 1
+      }
+      return (a.rank ?? 0) - (b.rank ?? 0)
+    })
+    return this
+  }
+
+  public [Symbol.iterator] (): Iterator<AppRoute<TState>> {
+    return this._routes[Symbol.iterator]()
+  }
+}

package/src/app/routeRank.ts

@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Defines the priority ranking for route evaluation in the agent hosting framework.
+ *
+ * @remarks
+ * Routes are evaluated in ascending order of their rank values, allowing for precise
+ * control over which routes are processed first when multiple routes could match
+ * the same request.
+ *
+ * @example
+ * ```typescript
+ * // High priority route that should be evaluated first
+ * this.onMessage('urgent', handler, undefined, RouteRank.First);
+ *
+ * // Normal priority route with default ranking
+ * this.onMessage('data', handler, undefined, RouteRank.Unspecified);
+ *
+ * // Fallback route that should be evaluated last
+ * this.onActivity('message', fallbackHandler, undefined, RouteRank.Last);
+ *
+ * // Multiple routes with same pattern - first ranked executes first
+ * this.onMessage('dupText', handler1, undefined, RouteRank.Last);
+ * this.onMessage('dupText', handler2, undefined, RouteRank.First); // This executes first
+ * ```
+ */
+export enum RouteRank {
+  /**
+   * Highest priority rank (value: 0). Routes with this rank are evaluated first
+   * before any other routes. Use this for critical routes that must take precedence
+   * over all others, such as high-priority message handlers or override handlers
+   * that should execute before any other matching routes.
+   */
+  First = 0,
+
+  /**
+   * Lowest priority rank (value: Number.MAX_VALUE). Routes with this rank are
+   * evaluated last, after all other routes have been considered. Ideal for
+   * catch-all message handlers, fallback activity handlers, or default responses
+   * that should only match when no other routes apply.
+   */
+  Last = Number.MAX_VALUE,
+
+  /**
+   * Default priority rank (value: Number.MAX_VALUE / 2). This is the standard
+   * rank for most routes that don't require special ordering. Routes with this
+   * rank are evaluated after high-priority routes but before low-priority ones.
+   * Use this when you don't need to specify a particular evaluation order.
+   */
+  Unspecified = Number.MAX_VALUE / 2
+}

package/src/app/streaming/streamingResponse.ts

@@ -7,7 +7,7 @@ import { Activity, addAIToActivity, Attachment, Entity } from '@microsoft/agents
 import { TurnContext } from '../../turnContext'
 import { Citation } from './citation'
 import { CitationUtil } from './citationUtil'
-import { debug } from '../../logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 import { ClientCitation, SensitivityUsageInfo } from '@microsoft/agents-activity/src/entity/AIEntity'
 
 const logger = debug('agents:streamingResponse')
@@ -89,10 +89,11 @@ export class StreamingResponse {
     this.queueActivity(() => Activity.fromObject({
       type: 'typing',
       text,
-      channelData: {
+      entities: [{
+        type: 'streaminfo',
         streamType: 'informative',
         streamSequence: this._nextSequence++
-      } as StreamingChannelData
+      }]
     }))
   }
 
@@ -242,20 +243,22 @@ export class StreamingResponse {
           type: 'message',
           text: this._message || 'end of stream response',
           attachments: this._attachments,
-          channelData: {
+          entities: [{
+            type: 'streaminfo',
             streamType: 'final',
             streamSequence: this._nextSequence++
-          } as StreamingChannelData
+          }]
         })
       } else {
         // Send typing activity
         return Activity.fromObject({
           type: 'typing',
           text: this._message,
-          channelData: {
+          entities: [{
+            type: 'streaminfo',
             streamType: 'streaming',
             streamSequence: this._nextSequence++
-          } as StreamingChannelData
+          }]
         })
       }
     })
@@ -270,7 +273,7 @@ export class StreamingResponse {
     // If there's no sync in progress, start one
     if (!this._queueSync) {
       this._queueSync = this.drainQueue().catch((err) => {
-        logger.error(`Error occured when sending activity while streaming: "${err}".`)
+        logger.error(`Error occurred when sending activity while streaming: "${JSON.stringify(err)}".`)
         // throw err
       })
     }
@@ -311,20 +314,19 @@ export class StreamingResponse {
     // Set activity ID to the assigned stream ID
     if (this._streamId) {
       activity.id = this._streamId
-      activity.channelData = Object.assign({}, activity.channelData, { streamId: this._streamId })
+      if (!activity.entities) {
+        activity.entities = []
+      }
+      if (!activity.entities[0]) {
+        activity.entities[0] = {} as Entity
+      }
+      activity.entities[0].streamId = this._streamId
     }
 
-    activity.entities = [
-      {
-        type: 'streaminfo',
-        ...activity.channelData
-      } as Entity
-    ]
-
     if (this._citations && this._citations.length > 0 && !this._ended) {
       // Filter out the citations unused in content.
       const currCitations = CitationUtil.getUsedCitations(this._message, this._citations) ?? undefined
-      activity.entities.push({
+      activity.entities!.push({
         type: 'https://schema.org/Message',
         '@type': 'Message',
         '@context': 'https://schema.org',
@@ -335,28 +337,14 @@ export class StreamingResponse {
 
     // Add in Powered by AI feature flags
     if (this._ended) {
-      if (this._enableFeedbackLoop && this._feedbackLoopType) {
-        activity.channelData = Object.assign({}, activity.channelData, {
-          feedbackLoop: { type: this._feedbackLoopType }
-        })
-      } else {
-        activity.channelData = Object.assign({}, activity.channelData, {
-          feedbackLoopEnabled: this._enableFeedbackLoop
-        })
+      activity.channelData = {
+        feedbackLoopEnabled: this._enableFeedbackLoop ?? false,
+        ...(this._feedbackLoopType ? { type: this._feedbackLoopType } : {})
       }
 
       // Add in Generated by AI
       if (this._enableGeneratedByAILabel) {
         addAIToActivity(activity, this._citations, this._sensitivityLabel)
-        // activity.entities.push({
-        //   type: 'https://schema.org/Message',
-        //   '@type': 'Message',
-        //   '@context': 'https://schema.org',
-        //   '@id': '',
-        //   additionalType: ['AIGeneratedContent'],
-        //   citation: this._citations && this._citations.length > 0 ? this._citations : [],
-        //   usageInfo: this._sensitivityLabel
-        // } as unknown as Entity)
       }
     }
 
@@ -370,38 +358,3 @@ export class StreamingResponse {
     }
   }
 }
-
-/**
- * @private
- * Structure of the outgoing channelData field for streaming responses.
- * @remarks
- * The expected sequence of streamTypes is:
- *
- * `informative`, `streaming`, `streaming`, ..., `final`.
- *
- * Once a `final` message is sent, the stream is considered ended.
- */
-interface StreamingChannelData {
-  /**
-     * The type of message being sent.
-     * @remarks
-     * `informative` - An informative update.
-     * `streaming` - A chunk of partial message text.
-     * `final` - The final message.
-     */
-  streamType: 'informative' | 'streaming' | 'final';
-
-  /**
-     * Sequence number of the message in the stream.
-     * @remarks
-     * Starts at 1 for the first message and increments from there.
-     */
-  streamSequence: number;
-
-  /**
-     * ID of the stream.
-     * @remarks
-     * Assigned after the initial update is sent.
-     */
-  streamId?: string;
-}

package/src/app/turnState.ts

@@ -8,7 +8,7 @@ import { AppMemory } from './appMemory'
 import { InputFile } from './inputFileDownloader'
 import { TurnStateEntry } from './turnStateEntry'
 import { TurnContext } from '../turnContext'
-import { debug } from '../logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 
 const logger = debug('agents:turnState')
 
@@ -43,6 +43,8 @@ export interface DefaultTempState {
  * Base class defining a collection of turn state scopes.
  * @remarks
  * Developers can create a derived class that extends `TurnState` to add additional state scopes.
+ *
+ * @example
  * ```JavaScript
  * class MyTurnState extends TurnState {
  *   protected async onComputeStorageKeys(context) {

package/src/auth/authConfiguration.ts

@@ -50,6 +50,8 @@ export interface AuthConfiguration {
 
 /**
  * Loads the authentication configuration from environment variables.
+ *
+ * @example
  * ```
  * tenantId=your-tenant-id
  * clientId=your-client-id
@@ -106,6 +108,8 @@ export const loadAuthConfigFromEnv: (cnxName?: string) => AuthConfiguration = (c
 
 /**
  * Loads the agent authentication configuration from previous version environment variables.
+ *
+ * @example
  * ```
  * MicrosoftAppId=your-client-id
  * MicrosoftAppPassword=your-client-secret

package/src/auth/authProvider.ts

@@ -6,7 +6,7 @@
 import { AuthConfiguration } from './authConfiguration'
 
 /**
- * Interface representing an authentication provider.
+ * Represents an authentication provider.
  */
 export interface AuthProvider {
   /**

package/src/auth/jwt-middleware.ts

@@ -8,7 +8,7 @@ import { Response, NextFunction } from 'express'
 import { Request } from './request'
 import jwksRsa, { JwksClient, SigningKey } from 'jwks-rsa'
 import jwt, { JwtHeader, JwtPayload, SignCallback, GetPublicKeyOrSecret } from 'jsonwebtoken'
-import { debug } from '../logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 
 const logger = debug('agents:jwt-middleware')
 

package/src/auth/msalTokenCredential.ts

@@ -1,8 +1,23 @@
 import { GetTokenOptions, TokenCredential } from '@azure/core-auth'
 import { AuthConfiguration, MsalTokenProvider } from './'
 
+/**
+ * Token credential implementation that uses MSAL (Microsoft Authentication Library) to acquire access tokens.
+ * Implements the Azure Core Auth TokenCredential interface for authentication scenarios.
+ */
 export class MsalTokenCredential implements TokenCredential {
+  /**
+   * Creates a new instance of MsalTokenCredential.
+   * @param authConfig The authentication configuration to use for token acquisition.
+   */
   constructor (private authConfig: AuthConfiguration) {}
+
+  /**
+   * Retrieves an access token for the specified scopes using MSAL authentication.
+   * @param scopes Array of scopes for which to request an access token. The first scope is used to determine the resource.
+   * @param options Optional parameters for token retrieval (currently unused).
+   * @returns Promise that resolves to an access token with expiration timestamp.
+   */
   public async getToken (scopes: string[], options?: GetTokenOptions) {
     const scope = scopes[0].substring(0, scopes[0].lastIndexOf('/'))
     const token = await new MsalTokenProvider().getAccessToken(this.authConfig, scope)

package/src/auth/msalTokenProvider.ts

@@ -6,7 +6,7 @@
 import { ConfidentialClientApplication, LogLevel, ManagedIdentityApplication, NodeSystemOptions } from '@azure/msal-node'
 import { AuthConfiguration } from './authConfiguration'
 import { AuthProvider } from './authProvider'
-import { debug } from '../logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 import { v4 } from 'uuid'
 
 import fs from 'fs'
@@ -82,7 +82,9 @@ export class MsalTokenProvider implements AuthProvider {
             logger.info(message)
             return
           case LogLevel.Warning:
-            logger.warn(message)
+            if (!message.includes('Warning - No client info in response')) {
+              logger.warn(message)
+            }
             return
           case LogLevel.Verbose:
             logger.debug(message)

package/src/baseAdapter.ts

@@ -8,7 +8,7 @@ import { AuthProvider } from './auth/authProvider'
 import { MsalTokenProvider } from './auth/msalTokenProvider'
 import { Middleware, MiddlewareHandler, MiddlewareSet } from './middlewareSet'
 import { TurnContext } from './turnContext'
-import { debug } from './logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 import { Activity, ConversationReference } from '@microsoft/agents-activity'
 import { ResourceResponse } from './connector-client/resourceResponse'
 import { AttachmentData } from './connector-client/attachmentData'
@@ -17,7 +17,19 @@ import { AttachmentInfo } from './connector-client/attachmentInfo'
 const logger = debug('agents:base-adapter')
 
 /**
- * Base class for all adapters, providing middleware and error handling capabilities.
+ * Abstract base class for all adapters in the Agents framework.
+ *
+ * @remarks
+ * This class provides core functionality for handling conversations, managing middleware,
+ * authentication, and error handling. Adapters are responsible for translating between
+ * the Agents framework and specific communication channels (like Teams, Web Chat, etc.).
+ *
+ * Key features:
+ * - Middleware pipeline for processing incoming and outgoing activities
+ * - Error handling and recovery mechanisms
+ * - Authentication provider integration
+ * - Abstract methods for channel-specific operations
+ * - Context management with revocable proxies for security
  */
 export abstract class BaseAdapter {
   /**
@@ -41,8 +53,19 @@ export abstract class BaseAdapter {
     await context.sendActivity('To continue to run this agent, please fix the source code.')
   }
 
+  /**
+   * Symbol key used to store agent identity information in the TurnContext.
+   */
   readonly AgentIdentityKey = Symbol('AgentIdentity')
+
+  /**
+   * Symbol key used to store connector client instances in the TurnContext.
+   */
   readonly ConnectorClientKey = Symbol('ConnectorClient')
+
+  /**
+   * Symbol key used to store OAuth scope information in the TurnContext.
+   */
   readonly OAuthScopeKey = Symbol('OAuthScope')
 
   /**

package/src/cards/adaptiveCard.ts

@@ -5,6 +5,8 @@
 
 /**
  * Represents an Adaptive Card, which is a card framework that enables developers to exchange UI content in a common and consistent way.
+ *
+ * @remarks
  * @see {@link https://learn.microsoft.com/adaptive-cards/ | Adaptive Cards Documentation}
  */
 export interface AdaptiveCard {

package/src/cards/animationCard.ts

@@ -8,7 +8,7 @@ import { MediaUrl } from './mediaUrl'
 import { ThumbnailUrl } from './thumbnailUrl'
 
 /**
- * Interface representing an Animation Card.
+ * Represents an Animation Card.
  */
 export interface AnimationCard {
   /** The title of the card. */

package/src/cards/audioCard.ts

@@ -8,7 +8,7 @@ import { MediaUrl } from './mediaUrl'
 import { ThumbnailUrl } from './thumbnailUrl'
 
 /**
- * Interface representing an Audio Card.
+ * Represents an Audio Card.
  */
 export interface AudioCard {
   /** The title of the card. */

package/src/cards/cardImage.ts

@@ -6,7 +6,7 @@
 import { CardAction } from '@microsoft/agents-activity'
 
 /**
- * Interface representing a Card Image.
+ * Represents a Card Image.
  */
 export interface CardImage {
   /** The URL of the image. */

package/src/cards/fact.ts

@@ -4,7 +4,7 @@
  */
 
 /**
- * Interface representing a Fact.
+ * Represents a Fact.
  */
 export interface Fact {
   /** The key of the fact. */

package/src/cards/heroCard.ts

@@ -7,7 +7,7 @@ import { CardAction } from '@microsoft/agents-activity'
 import { CardImage } from './cardImage'
 
 /**
- * Interface representing a Hero Card.
+ * Represents a Hero Card.
  */
 export interface HeroCard {
   /** The title of the card. */

package/src/cards/o365ConnectorCardSection.ts

@@ -7,6 +7,11 @@ import { O365ConnectorCardActionBase } from './o365ConnectorCardActionBase'
 import { O365ConnectorCardFact } from './o365ConnectorCardFact'
 import { O365ConnectorCardImage } from './o365ConnectorCardImage'
 
+/**
+ * Defines the type of activity image to display in an O365 connector card section.
+ * - 'avatar': Displays the image as a profile avatar (typically circular or small)
+ * - 'article': Displays the image as an article thumbnail (typically rectangular or larger)
+ */
 export type ActivityImageType = 'avatar' | 'article'
 
 /**

package/src/cloudAdapter.ts

@@ -15,7 +15,7 @@ import { Activity, ActivityEventNames, ActivityTypes, Channels, ConversationRefe
 import { ResourceResponse } from './connector-client/resourceResponse'
 import { MsalTokenProvider } from './auth/msalTokenProvider'
 import * as uuid from 'uuid'
-import { debug } from './logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 import { StatusCodes } from './statusCodes'
 import { InvokeResponse } from './invoke/invokeResponse'
 import { AttachmentInfo } from './connector-client/attachmentInfo'
@@ -27,6 +27,7 @@ const logger = debug('agents:cloud-adapter')
 /**
  * Adapter for handling agent interactions with various channels through cloud-based services.
  *
+ * @remarks
  * CloudAdapter processes incoming HTTP requests from Microsoft Bot Framework channels,
  * authenticates them, and generates outgoing responses. It manages the communication
  * flow between agents and users across different channels, handling activities, attachments,
@@ -55,6 +56,33 @@ export class CloudAdapter extends BaseAdapter {
     }
   }
 
+  /**
+   * Determines whether a connector client is needed based on the delivery mode and service URL of the given activity.
+   *
+   * @param activity - The activity to evaluate.
+   * @returns true if a ConnectorClient is needed, false otherwise.
+   *  A connector client is required if the activity's delivery mode is not "ExpectReplies"
+   *  and the service URL is not null or empty.
+   * @protected
+   */
+  protected resolveIfConnectorClientIsNeeded (activity: Activity): boolean {
+    if (!activity) {
+      throw new TypeError('`activity` parameter required')
+    }
+
+    switch (activity.deliveryMode) {
+      case DeliveryModes.ExpectReplies:
+        if (!activity.serviceUrl) {
+          logger.debug('DeliveryMode = ExpectReplies, connector client is not needed')
+          return false
+        }
+        break
+      default:
+        break
+    }
+    return true
+  }
+
   /**
    * Creates a connector client for a specific service URL and scope.
    *
@@ -200,9 +228,13 @@ export class CloudAdapter extends BaseAdapter {
     logger.debug('Received activity: ', activity)
     const context = this.createTurnContext(activity, logic)
     const scope = request.user?.azp ?? request.user?.appid ?? 'https://api.botframework.com'
-    logger.debug('Creating connector client with scope: ', scope)
-    this.connectorClient = await this.createConnectorClient(activity.serviceUrl!, scope)
-    this.setConnectorClient(context)
+
+    // if Delivery Mode == ExpectReplies, we don't need a connector client.
+    if (this.resolveIfConnectorClientIsNeeded(activity)) {
+      logger.debug('Creating connector client with scope: ', scope)
+      this.connectorClient = await this.createConnectorClient(activity.serviceUrl!, scope)
+      this.setConnectorClient(context)
+    }
 
     if (
       activity?.type === ActivityTypes.InvokeResponse ||

package/src/connector-client/connectorClient.ts

@@ -2,7 +2,7 @@
 import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios'
 import { AuthConfiguration } from '../auth/authConfiguration'
 import { AuthProvider } from '../auth/authProvider'
-import { debug } from '../logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 import { Activity, ChannelAccount, ConversationParameters } from '@microsoft/agents-activity'
 import { ConversationsResult } from './conversationsResult'
 import { ConversationResourceResponse } from './conversationResourceResponse'

package/src/index.ts

@@ -20,12 +20,10 @@ export * from './baseAdapter'
 export * from './cloudAdapter'
 export * from './middlewareSet'
 export * from './claimsIdentity'
-export * from './logger'
 export * from './messageFactory'
 export * from './statusCodes'
 export * from './turnContext'
 export * from './turnContextStateCollection'
-export * from './logger'
 export * from './storage/storage'
 
 export * from './agent-client'

package/src/middlewareSet.ts

@@ -1,6 +1,6 @@
 /** * Copyright (c) Microsoft Corporation. All rights reserved. * Licensed under the MIT License. */
 import { TurnContext } from './turnContext'
-import { debug } from './logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 
 const logger = debug('agents:middleware')
 

package/src/oauth/oAuthFlow.ts

@@ -1,6 +1,6 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
-import { debug } from './../logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 import { Activity, ActivityTypes, Attachment } from '@microsoft/agents-activity'
 import {
   CardFactory,