@microsoft/agents-hosting 0.4.3 → 0.5.4-ga4d0401645

package/src/app/streaming/streamingResponse.ts

@@ -0,0 +1,406 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Activity, Attachment, Entity } from '@microsoft/agents-activity'
+import { TurnContext } from '../../turnContext'
+import { ClientCitation } from './clientCitation'
+import { SensitivityUsageInfo } from './sensitivityUsageInfo'
+import { Citation } from './message'
+import { Utilities } from './utilities'
+
+/**
+ * A helper class for streaming responses to the client.
+ * @remarks
+ * This class is used to send a series of updates to the client in a single response. The expected
+ * sequence of calls is:
+ *
+ * `sendInformativeUpdate()`, `sendTextChunk()`, `sendTextChunk()`, ..., `endStream()`.
+ *
+ * Once `endStream()` is called, the stream is considered ended and no further updates can be sent.
+ */
+export class StreamingResponse {
+  private readonly _context: TurnContext
+  private _nextSequence: number = 1
+  private _streamId?: string
+  private _message: string = ''
+  private _attachments?: Attachment[]
+  private _ended = false
+
+  // Queue for outgoing activities
+  private _queue: Array<() => Activity> = []
+  private _queueSync: Promise<void> | undefined
+  private _chunkQueued = false
+
+  // Powered by AI feature flags
+  private _enableFeedbackLoop = false
+  private _feedbackLoopType?: 'default' | 'custom'
+  private _enableGeneratedByAILabel = false
+  private _citations?: ClientCitation[] = []
+  private _sensitivityLabel?: SensitivityUsageInfo
+
+  /**
+     * Creates a new StreamingResponse instance.
+     * @param {TurnContext} context - Context for the current turn of conversation with the user.
+     * @returns {TurnContext} - The context for the current turn of conversation with the user.
+     */
+  public constructor (context: TurnContext) {
+    this._context = context
+  }
+
+  /**
+     * Gets the stream ID of the current response.
+     * @returns {string | undefined} - The stream ID of the current response.
+     * @remarks
+     * Assigned after the initial update is sent.
+     */
+  public get streamId (): string | undefined {
+    return this._streamId
+  }
+
+  /**
+     * Gets the citations of the current response.
+     */
+  public get citations (): ClientCitation[] | undefined {
+    return this._citations
+  }
+
+  /**
+     * Gets the number of updates sent for the stream.
+     * @returns {number} - The number of updates sent for the stream.
+     */
+  public get updatesSent (): number {
+    return this._nextSequence - 1
+  }
+
+  /**
+     * Queues an informative update to be sent to the client.
+     * @param {string} text Text of the update to send.
+     */
+  public queueInformativeUpdate (text: string): void {
+    if (this._ended) {
+      throw new Error('The stream has already ended.')
+    }
+
+    // Queue a typing activity
+    this.queueActivity(() => Activity.fromObject({
+      type: 'typing',
+      text,
+      channelData: {
+        streamType: 'informative',
+        streamSequence: this._nextSequence++
+      } as StreamingChannelData
+    }))
+  }
+
+  /**
+     * Queues a chunk of partial message text to be sent to the client
+     * @remarks
+     * The text we be sent as quickly as possible to the client. Chunks may be combined before
+     * delivery to the client.
+     * @param {string} text Partial text of the message to send.
+     * @param {Citation[]} citations Citations to be included in the message.
+     */
+  public queueTextChunk (text: string, citations?: Citation[]): void {
+    if (this._ended) {
+      throw new Error('The stream has already ended.')
+    }
+
+    // Update full message text
+    this._message += text
+
+    // If there are citations, modify the content so that the sources are numbers instead of [doc1], [doc2], etc.
+    this._message = Utilities.formatCitationsResponse(this._message)
+
+    // Queue the next chunk
+    this.queueNextChunk()
+  }
+
+  /**
+     * Ends the stream by sending the final message to the client.
+     * @returns {Promise<void>} - A promise representing the async operation
+     */
+  public endStream (): Promise<void> {
+    if (this._ended) {
+      throw new Error('The stream has already ended.')
+    }
+
+    // Queue final message
+    this._ended = true
+    this.queueNextChunk()
+
+    // Wait for the queue to drain
+    return this.waitForQueue()
+  }
+
+  /**
+     * Sets the attachments to attach to the final chunk.
+     * @param attachments List of attachments.
+     */
+  public setAttachments (attachments: Attachment[]): void {
+    this._attachments = attachments
+  }
+
+  /**
+     * Sets the sensitivity label to attach to the final chunk.
+     * @param sensitivityLabel The sensitivty label.
+     */
+  public setSensitivityLabel (sensitivityLabel: SensitivityUsageInfo): void {
+    this._sensitivityLabel = sensitivityLabel
+  }
+
+  /**
+     * Sets the citations for the full message.
+     * @param {Citation[]} citations Citations to be included in the message.
+     */
+  public setCitations (citations: Citation[]): void {
+    if (citations.length > 0) {
+      if (!this._citations) {
+        this._citations = []
+      }
+      let currPos = this._citations.length
+
+      for (const citation of citations) {
+        const clientCitation: ClientCitation = {
+          '@type': 'Claim',
+          position: currPos + 1,
+          appearance: {
+            '@type': 'DigitalDocument',
+            name: citation.title || `Document #${currPos + 1}`,
+            abstract: Utilities.snippet(citation.content, 477)
+          }
+        }
+        currPos++
+        this._citations.push(clientCitation)
+      }
+    }
+  }
+
+  /**
+     * Sets the Feedback Loop in Teams that allows a user to
+     * give thumbs up or down to a response.
+     * Default is `false`.
+     * @param enableFeedbackLoop If true, the feedback loop is enabled.
+     */
+  public setFeedbackLoop (enableFeedbackLoop: boolean): void {
+    this._enableFeedbackLoop = enableFeedbackLoop
+  }
+
+  /**
+     * Sets the type of UI to use for the feedback loop.
+     * @param feedbackLoopType The type of the feedback loop.
+     */
+  public setFeedbackLoopType (feedbackLoopType: 'default' | 'custom'): void {
+    this._feedbackLoopType = feedbackLoopType
+  }
+
+  /**
+     * Sets the the Generated by AI label in Teams
+     * Default is `false`.
+     * @param enableGeneratedByAILabel If true, the label is added.
+     */
+  public setGeneratedByAILabel (enableGeneratedByAILabel: boolean): void {
+    this._enableGeneratedByAILabel = enableGeneratedByAILabel
+  }
+
+  /**
+     * Returns the most recently streamed message.
+     * @returns The streamed message.
+     */
+  public getMessage (): string {
+    return this._message
+  }
+
+  /**
+     * Waits for the outgoing activity queue to be empty.
+     * @returns {Promise<void>} - A promise representing the async operation.
+     */
+  public waitForQueue (): Promise<void> {
+    return this._queueSync || Promise.resolve()
+  }
+
+  /**
+     * Queues the next chunk of text to be sent to the client.
+     * @private
+     */
+  private queueNextChunk (): void {
+    // Are we already waiting to send a chunk?
+    if (this._chunkQueued) {
+      return
+    }
+
+    // Queue a chunk of text to be sent
+    this._chunkQueued = true
+    this.queueActivity(() => {
+      this._chunkQueued = false
+      if (this._ended) {
+        // Send final message
+        return Activity.fromObject({
+          type: 'message',
+          text: this._message,
+          attachments: this._attachments,
+          channelData: {
+            streamType: 'final'
+          } as StreamingChannelData
+        })
+      } else {
+        // Send typing activity
+        return Activity.fromObject({
+          type: 'typing',
+          text: this._message,
+          channelData: {
+            streamType: 'streaming',
+            streamSequence: this._nextSequence++
+          } as StreamingChannelData
+        })
+      }
+    })
+  }
+
+  /**
+     * Queues an activity to be sent to the client.
+     */
+  private queueActivity (factory: () => Activity): void {
+    this._queue.push(factory)
+
+    // If there's no sync in progress, start one
+    if (!this._queueSync) {
+      this._queueSync = this.drainQueue().catch((err) => {
+        console.error(`Error occured when sending activity while streaming: "${err}".`)
+        throw err
+      })
+    }
+  }
+
+  /**
+     * Sends any queued activities to the client until the queue is empty.
+     * @returns {Promise<void>} - A promise that will be resolved once the queue is empty.
+     * @private
+     */
+  private async drainQueue (): Promise<void> {
+    // eslint-disable-next-line no-async-promise-executor
+    return new Promise<void>(async (resolve, reject) => {
+      try {
+        while (this._queue.length > 0) {
+          // Get next activity from queue
+          const factory = this._queue.shift()!
+          const activity = factory()
+
+          // Send activity
+          await this.sendActivity(activity)
+        }
+
+        resolve()
+      } catch (err) {
+        reject(err)
+      } finally {
+        // Queue is empty, mark as idle
+        this._queueSync = undefined
+      }
+    })
+  }
+
+  /**
+     * Sends an activity to the client and saves the stream ID returned.
+     * @param {Activity} activity - The activity to send.
+     * @returns {Promise<void>} - A promise representing the async operation.
+     * @private
+     */
+  private async sendActivity (activity: Activity): Promise<void> {
+    // Set activity ID to the assigned stream ID
+    if (this._streamId) {
+      activity.id = this._streamId
+      activity.channelData = Object.assign({}, activity.channelData, { 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 = Utilities.getUsedCitations(this._message, this._citations) ?? undefined
+      activity.entities.push({
+        type: 'https://schema.org/Message',
+        '@type': 'Message',
+        '@context': 'https://schema.org',
+        '@id': '',
+        citation: currCitations
+      } as unknown as Entity)
+    }
+
+    // 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
+        })
+      }
+
+      // Add in Generated by AI
+      if (this._enableGeneratedByAILabel) {
+        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)
+      }
+    }
+
+    // Send activity
+    const response = await this._context.sendActivity(activity)
+    // await new Promise((resolve) => setTimeout(resolve, 1500))
+
+    // Save assigned stream ID
+    if (!this._streamId) {
+      this._streamId = response?.id
+    }
+  }
+}
+
+/**
+ * @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/streaming/utilities.ts

@@ -0,0 +1,108 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ClientCitation } from './clientCitation'
+
+// import { stringify } from 'yaml'
+
+// import { Tokenizer } from './tokenizers'
+
+/**
+ * Utility functions for manipulating .
+ */
+export class Utilities {
+//   /**
+//      * Converts a value to a string.
+//      * @remarks
+//      * Dates are converted to ISO strings and Objects are converted to JSON or YAML, whichever is shorter.
+//      * @param {Tokenizer} tokenizer Tokenizer to use for encoding.
+//      * @param {any} value Value to convert.
+//      * @param {boolean} asJSON Optional. If true objects will always be converted to JSON instead of YAML. Defaults to false.
+//      * @returns {string} Converted value.
+//      */
+//   public static toString (tokenizer: Tokenizer, value: any, asJSON: boolean = false): string {
+//     if (value === undefined || value === null) {
+//       return ''
+//     } else if (typeof value === 'object') {
+//       if (typeof value.toISOString === 'function') {
+//         return value.toISOString()
+//       } else if (asJSON) {
+//         return JSON.stringify(value)
+//       } else {
+//         // Return shorter version of object
+//         const asYaml = stringify(value)
+//         const asJSON = JSON.stringify(value)
+//         if (tokenizer.encode(asYaml).length <= tokenizer.encode(asJSON).length) {
+//           return asYaml
+//         } else {
+//           return asJSON
+//         }
+//       }
+//     } else {
+//       return value.toString()
+//     }
+//   }
+
+  /**
+     *
+     * Clips the text to a maximum length in case it exceeds the limit.
+     * @param {string} text The text to clip.
+     * @param {number} maxLength The maximum length of the text to return, cutting off the last whole word.
+     * @returns {string} The modified text
+     */
+  public static snippet (text: string, maxLength: number): string {
+    if (text.length <= maxLength) {
+      return text
+    }
+    let snippet = text.slice(0, maxLength)
+    snippet = snippet.slice(0, Math.min(snippet.length, snippet.lastIndexOf(' ')))
+    snippet += '...'
+    return snippet
+  }
+
+  /**
+     * Convert citation tags `[doc(s)n]` to `[n]` where n is a number.
+     * @param {string} text The text to format.
+     * @returns {string} The formatted text.
+     */
+  public static formatCitationsResponse (text: string): string {
+    return text.replace(/\[docs?(\d+)\]/gi, '[$1]')
+  }
+
+  /**
+     * Get the citations used in the text. This will remove any citations that are included in the citations array from the response but not referenced in the text.
+     * @param {string} text - The text to search for citation references, i.e. [1], [2], etc.
+     * @param {ClientCitation[]} citations - The list of citations to search for.
+     * @returns {ClientCitation[] | undefined} The list of citations used in the text.
+     */
+  public static getUsedCitations (text: string, citations: ClientCitation[]): ClientCitation[] | undefined {
+    const regex = /\[(\d+)\]/gi
+    const matches = text.match(regex)
+
+    if (!matches) {
+      return undefined
+    }
+
+    // Remove duplicates
+    const filteredMatches = new Set()
+    matches.forEach((match) => {
+      if (filteredMatches.has(match)) {
+        return
+      }
+
+      filteredMatches.add(match)
+    })
+
+    // Add citations
+    const usedCitations: ClientCitation[] = []
+    filteredMatches.forEach((match) => {
+      const found = citations.find((citation) => `[${citation.position}]` === match)
+      if (found) {
+        usedCitations.push(found)
+      }
+    })
+    return usedCitations
+  }
+}

package/src/auth/jwt-middleware.ts

@@ -21,7 +21,7 @@ const logger = debug('agents:jwt-middleware')
 const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtPayload> => {
   const getKey: GetPublicKeyOrSecret = (header: JwtHeader, callback: SignCallback) => {
     const payload = jwt.decode(raw) as JwtPayload
-
+    logger.info('jwt.decode ', JSON.stringify(payload))
     const jwksUri: string = payload.iss === 'https://api.botframework.com'
       ? 'https://login.botframework.com/v1/.well-known/keys'
       : `https://login.microsoftonline.com/${config.tenantId}/discovery/v2.0/keys`

package/src/baseAdapter.ts

@@ -175,12 +175,12 @@ export abstract class BaseAdapter {
 
     try {
       await this.middleware.run(pContext.proxy, async () => await next(pContext.proxy))
-    } catch (err) {
+    } catch (err: Error | any) {
       if (this.onTurnError) {
         if (err instanceof Error) {
           await this.onTurnError(pContext.proxy, err)
         } else {
-          throw new Error('Unknown error type')
+          throw new Error('Unknown error type: ' + err.message)
         }
       } else {
         throw err

package/src/cards/adaptiveCard.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Represents an Adaptive Card, which is a card framework that enables developers to exchange UI content in a common and consistent way.
+ * @see {@link https://learn.microsoft.com/adaptive-cards/ | Adaptive Cards Documentation}
+ */
+export interface AdaptiveCard {
+  /**
+   * The type of the card, which must always be 'AdaptiveCard'.
+   */
+  type: 'AdaptiveCard'
+  [key: string]: any
+}

package/src/cards/index.ts

@@ -16,3 +16,4 @@ export * from './taskModuleAction'
 export * from './thumbnailCard'
 export * from './videoCard'
 export * from './thumbnailUrl'
+export * from './adaptiveCard'

package/src/cloudAdapter.ts

@@ -198,25 +198,23 @@ 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 (
       activity?.type === ActivityTypes.InvokeResponse ||
       activity?.type === ActivityTypes.Invoke ||
       activity?.deliveryMode === DeliveryModes.ExpectReplies
     ) {
-      const context = this.createTurnContext(activity, logic)
       await this.runMiddleware(context, logic)
       const invokeResponse = this.processTurnResults(context)
       logger.debug('Activity Response (invoke/expect replies): ', invokeResponse)
       return end(invokeResponse?.status ?? StatusCodes.OK, JSON.stringify(invokeResponse?.body), true)
     }
 
-    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)
-
-    const context = this.createTurnContext(activity, logic)
-    this.setConnectorClient(context)
     await this.runMiddleware(context, logic)
     const invokeResponse = this.processTurnResults(context)