@microsoft/agents-hosting 0.4.3 → 0.5.4-ga4d0401645

package/src/app/agentApplication.ts

@@ -4,18 +4,20 @@
  */
 
 import { Activity, ActivityTypes, ConversationReference } from '@microsoft/agents-activity'
-import { TurnState } from './turnState'
 import { BaseAdapter } from '../baseAdapter'
-import { AgentApplicationOptions } from './agentApplicationOptions'
-import { RouteSelector } from './routeSelector'
-import { RouteHandler } from './routeHandler'
-import { ConversationUpdateEvents } from './conversationUpdateEvents'
-import { TurnEvents } from './turnEvents'
-import { AppRoute } from './appRoute'
-import { TurnContext } from '../turnContext'
 import { ResourceResponse } from '../connector-client'
 import { debug } from '../logger'
+import { TurnContext } from '../turnContext'
+import { AdaptiveCardsActions } from './adaptiveCards'
+import { AgentApplicationOptions } from './agentApplicationOptions'
+import { AppRoute } from './appRoute'
+import { ConversationUpdateEvents } from './conversationUpdateEvents'
+import { AgentExtension } from './extensions'
 import { Authorization } from './oauth/authorization'
+import { RouteHandler } from './routeHandler'
+import { RouteSelector } from './routeSelector'
+import { TurnEvents } from './turnEvents'
+import { TurnState } from './turnState'
 
 const logger = debug('agents:agent-application')
 
@@ -46,16 +48,21 @@ export class AgentApplication<TState extends TurnState> {
   protected readonly _afterTurn: ApplicationEventHandler<TState>[] = []
   private readonly _adapter?: BaseAdapter
   private readonly _authorization?: Authorization
-  private _typingTimer: any
+  private _typingTimer: NodeJS.Timeout | undefined
+  protected readonly _extensions: AgentExtension<TState>[] = []
+  private readonly _adaptiveCards: AdaptiveCardsActions<TState>
 
   public constructor (options?: Partial<AgentApplicationOptions<TState>>) {
     this._options = {
       ...options,
       turnStateFactory: options?.turnStateFactory || (() => new TurnState() as TState),
       startTypingTimer: options?.startTypingTimer !== undefined ? options.startTypingTimer : false,
-      longRunningMessages: options?.longRunningMessages !== undefined ? options.longRunningMessages : false
+      longRunningMessages: options?.longRunningMessages !== undefined ? options.longRunningMessages : false,
+      removeRecipientMention: options?.removeRecipientMention !== undefined ? options.removeRecipientMention : true,
     }
 
+    this._adaptiveCards = new AdaptiveCardsActions<TState>(this)
+
     if (this._options.adapter) {
       this._adapter = this._options.adapter
     }
@@ -65,9 +72,7 @@ export class AgentApplication<TState extends TurnState> {
     }
 
     if (this._options.longRunningMessages && !this._adapter && !this._options.agentAppId) {
-      throw new Error(
-        'The Application.longRunningMessages property is unavailable because no adapter or agentAppId was configured.'
-      )
+      throw new Error('The Application.longRunningMessages property is unavailable because no adapter was configured in the app.')
     }
   }
 
@@ -76,13 +81,7 @@ export class AgentApplication<TState extends TurnState> {
    * @throws Error if the adapter is not configured.
    */
   public get adapter (): BaseAdapter {
-    if (!this._adapter) {
-      throw new Error(
-        'The Application.adapter property is unavailable because it was not configured when creating the Application.'
-      )
-    }
-
-    return this._adapter
+    return this._adapter!
   }
 
   /**
@@ -91,11 +90,8 @@ export class AgentApplication<TState extends TurnState> {
    */
   public get authorization (): Authorization {
     if (!this._authorization) {
-      throw new Error(
-        'The Application.authorization property is unavailable because no authentication options were configured.'
-      )
+      throw new Error('The Application.authorization property is unavailable because no authorization options were configured.')
     }
-
     return this._authorization
   }
 
@@ -107,6 +103,10 @@ export class AgentApplication<TState extends TurnState> {
     return this._options
   }
 
+  public get adaptiveCards (): AdaptiveCardsActions<TState> {
+    return this._adaptiveCards
+  }
+
   /**
    * Sets an error handler for the application.
    *
@@ -129,7 +129,6 @@ export class AgentApplication<TState extends TurnState> {
     if (this._adapter) {
       this._adapter.onTurnError = handler
     }
-
     return this
   }
 
@@ -153,8 +152,8 @@ export class AgentApplication<TState extends TurnState> {
    * );
    * ```
    */
-  public addRoute (selector: RouteSelector, handler: RouteHandler<TState>): this {
-    this._routes.push({ selector, handler })
+  public addRoute (selector: RouteSelector, handler: RouteHandler<TState>, isInvokeRoute: boolean = false): this {
+    this._routes.push({ selector, handler, isInvokeRoute })
     return this
   }
 
@@ -316,12 +315,74 @@ export class AgentApplication<TState extends TurnState> {
       this.authorization.onSignInSuccess(handler)
     } else {
       throw new Error(
-        'The Application.authentication property is unavailable because no authentication options were configured.'
+        'The Application.authorization property is unavailable because no authorization options were configured.'
       )
     }
     return this
   }
 
+  /**
+   * Adds a handler for message reaction added events.
+   *
+   * @param handler - The handler function that will be called when a message reaction is added.
+   * @returns The current instance of the application.
+   *
+   * @remarks
+   * This method registers a handler that will be invoked when a user adds a reaction to a message,
+   * such as a like, heart, or other emoji reaction.
+   *
+   * Example usage:
+   * ```typescript
+   * app.onMessageReactionAdded(async (context, state) => {
+   *   const reactionsAdded = context.activity.reactionsAdded;
+   *   if (reactionsAdded && reactionsAdded.length > 0) {
+   *     await context.sendActivity(`Thanks for your ${reactionsAdded[0].type} reaction!`);
+   *   }
+   * });
+   * ```
+   */
+  public onMessageReactionAdded (handler: (context: TurnContext, state: TState) => Promise<void>): this {
+    const selector = async (context: TurnContext): Promise<boolean> => {
+      return context.activity.type === ActivityTypes.MessageReaction &&
+             Array.isArray(context.activity.reactionsAdded) &&
+             context.activity.reactionsAdded.length > 0
+    }
+
+    this.addRoute(selector, handler)
+    return this
+  }
+
+  /**
+   * Adds a handler for message reaction removed events.
+   *
+   * @param handler - The handler function that will be called when a message reaction is removed.
+   * @returns The current instance of the application.
+   *
+   * @remarks
+   * This method registers a handler that will be invoked when a user removes a reaction from a message,
+   * such as unliking or removing an emoji reaction.
+   *
+   * Example usage:
+   * ```typescript
+   * app.onMessageReactionRemoved(async (context, state) => {
+   *   const reactionsRemoved = context.activity.reactionsRemoved;
+   *   if (reactionsRemoved && reactionsRemoved.length > 0) {
+   *     await context.sendActivity(`You removed your ${reactionsRemoved[0].type} reaction.`);
+   *   }
+   * });
+   * ```
+   */
+  public onMessageReactionRemoved (handler: (context: TurnContext, state: TState) => Promise<void>): this {
+    const selector = async (context: TurnContext): Promise<boolean> => {
+      return context.activity.type === ActivityTypes.MessageReaction &&
+             Array.isArray(context.activity.reactionsRemoved) &&
+             context.activity.reactionsRemoved.length > 0
+    }
+
+    this.addRoute(selector, handler)
+    return this
+  }
+
   /**
    * Executes the application logic for a given turn context.
    *
@@ -355,8 +416,19 @@ export class AgentApplication<TState extends TurnState> {
    */
   public async runInternal (turnContext: TurnContext): Promise<boolean> {
     return await this.startLongRunningCall(turnContext, async (context) => {
-      this.startTypingTimer(context)
       try {
+        if (this._options.startTypingTimer) {
+          this.startTypingTimer(context)
+        }
+
+        if (this._options.removeRecipientMention && context.activity.type === ActivityTypes.Message) {
+          context.activity.removeRecipientMention()
+        }
+
+        if (this._options.normalizeMentions && context.activity.type === ActivityTypes.Message) {
+          context.activity.normalizeMentions()
+        }
+
         const { storage, turnStateFactory } = this._options
         const state = turnStateFactory()
         await state.load(context, storage)
@@ -497,6 +569,14 @@ export class AgentApplication<TState extends TurnState> {
     }
   }
 
+  public registerExtension<T extends AgentExtension<TState>> (extension: T, regcb : (ext:T) => void): void {
+    if (this._extensions.includes(extension)) {
+      throw new Error('Extension already registered')
+    }
+    this._extensions.push(extension)
+    regcb(extension)
+  }
+
   /**
    * Stops the typing indicator timer if it's currently running.
    *

package/src/app/agentApplicationBuilder.ts

@@ -3,11 +3,11 @@
  * Licensed under the MIT License.
  */
 
+import { Storage } from '../storage'
 import { AgentApplication } from './agentApplication'
 import { AgentApplicationOptions } from './agentApplicationOptions'
-import { TurnState } from './turnState'
-import { Storage } from '../storage'
 import { AuthorizationHandlers } from './oauth/authorization'
+import { TurnState } from './turnState'
 
 /**
  * Builder class for creating and configuring AgentApplication instances.

package/src/app/agentApplicationOptions.ts

@@ -4,10 +4,11 @@
  */
 
 import { CloudAdapter } from '../cloudAdapter'
-import { InputFileDownloader } from './inputFileDownloader'
-import { TurnState } from './turnState'
 import { Storage } from '../storage'
+import { AdaptiveCardsOptions } from './adaptiveCards'
+import { InputFileDownloader } from './inputFileDownloader'
 import { AuthorizationHandlers } from './oauth/authorization'
+import { TurnState } from './turnState'
 
 export interface AgentApplicationOptions<TState extends TurnState> {
   /**
@@ -49,4 +50,21 @@ export interface AgentApplicationOptions<TState extends TurnState> {
    * Handlers for managing authorization.
    */
   authorization?: AuthorizationHandlers;
+
+  /**
+   * Options for AdaptiveCard actions.
+   */
+  adaptiveCardsOptions?: AdaptiveCardsOptions;
+
+  /**
+   * Optional. If true, the agent will automatically remove mentions of the bot's name from incoming
+   * messages. Defaults to true.
+   */
+  removeRecipientMention?: boolean;
+
+  /**
+   * Optional. If true, the agent will automatically normalize mentions in incoming messages. Defaults to
+   * true.
+   */
+  normalizeMentions?: boolean
 }

package/src/app/appRoute.ts

@@ -17,4 +17,10 @@ export interface AppRoute<TState extends TurnState> {
    * The handler function that processes the activity if the selector matches.
    */
   handler: RouteHandler<TState>;
+
+  /**
+   * Indicates whether this route is an invoke route.
+   * Invoke routes are used for specific types of activities, such as messaging extensions.
+   */
+  isInvokeRoute?: boolean;
 }

package/src/app/attachmentDownloader.ts

@@ -46,6 +46,7 @@ export class AttachmentDownloader<TState extends TurnState = TurnState> implemen
       return Promise.resolve([])
     }
 
+    // TODO: from adapter
     const authProvider: AuthProvider = new MsalTokenProvider()
 
     const accessToken = await authProvider.getAccessToken(loadAuthConfigFromEnv(), 'https://api.botframework.com')

package/src/app/extensions.ts

@@ -0,0 +1,19 @@
+import { TurnContext } from '../turnContext'
+import { AgentApplication } from './agentApplication'
+import { RouteHandler } from './routeHandler'
+import { RouteSelector } from './routeSelector'
+import { TurnState } from './turnState'
+
+export class AgentExtension<TState extends TurnState> {
+  channelId: string
+  constructor (channelId: string) {
+    this.channelId = channelId
+  }
+
+  addRoute (app: AgentApplication<TState>, routeSelector: RouteSelector, routeHandler: RouteHandler<TurnState>, isInvokeRoute: boolean = false) {
+    const ensureChannelMatches = async (context: TurnContext) => {
+      return context.activity.channelId === this.channelId && routeSelector(context)
+    }
+    app.addRoute(ensureChannelMatches, routeHandler)
+  }
+}

package/src/app/index.ts

@@ -12,3 +12,5 @@ export * from './turnEvents'
 export * from './turnStateEntry'
 export * from './inputFileDownloader'
 export * from './appMemory'
+export * from './extensions'
+export * from './adaptiveCards'

package/src/app/streaming/AIEntity.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ClientCitation } from './clientCitation'
+import { SensitivityUsageInfo } from './sensitivityUsageInfo'
+
+export interface AIEntity {
+  /**
+     * Required as 'https://schema.org/Message'
+     */
+  type: 'https://schema.org/Message';
+
+  /**
+     * Required as 'Message
+     */
+  '@type': 'Message';
+
+  /**
+     * Required as 'https://schema.org
+     */
+  '@context': 'https://schema.org';
+
+  /**
+     * Must be left blank. This is for Bot Framework schema.
+     */
+  '@id': '';
+
+  /**
+     * Indicate that the content was generated by AI.
+     */
+  additionalType: ['AIGeneratedContent'];
+
+  /**
+     * Optional; if citations object is included, the  sent activity will include the citations, referenced in the activity text.
+     */
+  citation?: ClientCitation[];
+
+  /**
+     * Optional; if usage_info object is included, the sent activity will include the sensitivity usage information.
+     */
+  usageInfo?: SensitivityUsageInfo;
+}

package/src/app/streaming/actionCall.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * An action call to be requested by the LLM model. This type is a generic meant to be the equivalent of OpenAI's [`ChatCompletionMessageToolCall`](https://github.com/openai/openai-node/blob/master/src/resources/chat/completions.ts#L477), but is not tied to OpenAI's implementation in order to allow for flexibility for other models in the future.
+ */
+export interface ActionCall {
+  /**
+     * The ID of the tool call.
+     */
+  id: string;
+
+  /**
+     * The function that the model called.
+     */
+  function: {
+    /**
+         * The name of the function.
+         */
+    name: string;
+
+    /**
+         * The arguments to call the function with, as generated by the model in JSON
+         * format. Note that the model does not always generate valid JSON, and may
+         * hallucinate parameters not defined by your function schema. Validate the
+         * arguments in your code before calling your function.
+         */
+    arguments: string;
+  };
+
+  /**
+     * The type of the tool. Currently, only `function` is supported.
+     */
+  type: 'function';
+}

package/src/app/streaming/clientCitation.ts

@@ -0,0 +1,102 @@
+/**
+ * @module teams-ai
+ */
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { SensitivityUsageInfo } from './sensitivityUsageInfo'
+
+export type ClientCitationIconName =
+    | 'Microsoft Word'
+    | 'Microsoft Excel'
+    | 'Microsoft PowerPoint'
+    | 'Microsoft OneNote'
+    | 'Microsoft SharePoint'
+    | 'Microsoft Visio'
+    | 'Microsoft Loop'
+    | 'Microsoft Whiteboard'
+    | 'Adobe Illustrator'
+    | 'Adobe Photoshop'
+    | 'Adobe InDesign'
+    | 'Adobe Flash'
+    | 'Sketch'
+    | 'Source Code'
+    | 'Image'
+    | 'GIF'
+    | 'Video'
+    | 'Sound'
+    | 'ZIP'
+    | 'Text'
+    | 'PDF'
+
+/**
+ * Represents a Teams client citation to be included in a message. See Bot messages with AI-generated content for more details.
+ * https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bot-messages-ai-generated-content?tabs=before%2Cbotmessage
+ */
+export interface ClientCitation {
+  /**
+     * Required; must be "Claim"
+     */
+  '@type': 'Claim';
+
+  /**
+     * Required. Number and position of the citation.
+     */
+  position: number;
+  appearance: {
+    /**
+         * Required; Must be 'DigitalDocument'
+         */
+    '@type': 'DigitalDocument';
+
+    /**
+         * Name of the document. (max length 80)
+         */
+    name: string;
+
+    /**
+         * Stringified adaptive card with additional information about the citation.
+         * It is rendered within the modal.
+         */
+    text?: string;
+
+    /**
+         * URL of the document. This will make the name of the citation clickable and direct the user to the specified URL.
+         */
+    url?: string;
+
+    /**
+         * Extract of the referenced content. (max length 160)
+         */
+    abstract: string;
+
+    /**
+         * Encoding format of the `citation.appearance.text` field.
+         */
+    encodingFormat?: 'application/vnd.microsoft.card.adaptive';
+
+    /**
+         * Information about the citation’s icon.
+         */
+    image?: {
+      '@type': 'ImageObject';
+
+      /**
+             * The image/icon name
+             */
+      name: ClientCitationIconName;
+    };
+
+    /**
+         * Optional; set by developer. (max length 3) (max keyword length 28)
+         */
+    keywords?: string[];
+
+    /**
+         * Optional sensitivity content information.
+         */
+    usageInfo?: SensitivityUsageInfo;
+  };
+}

package/src/app/streaming/message.ts

@@ -0,0 +1,125 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ActionCall } from './actionCall'
+
+/**
+ * A message object sent to or received from an LLM.
+ * @param TContent Optional. Type of the message content. Defaults to `string`
+ */
+export interface Message<TContent = string> {
+  /**
+     * The messages role. Typically 'system', 'user', 'assistant', 'tool', 'function'.
+     */
+  role: string;
+
+  /**
+     * Text of the message.
+     */
+  content: TContent | undefined;
+
+  /**
+     * Optional. A named function to call.
+     */
+  function_call?: FunctionCall;
+
+  /**
+     * The context used for the message.
+     */
+  context?: MessageContext;
+
+  /**
+     * Optional. Name of the function that was called.
+     */
+  name?: string;
+
+  /**
+     * Optional. The action or tool to be called by the model when using 'tools' augmentation. In OpenAI, this is the tool_calls property returned from the model.
+     */
+  action_calls?: ActionCall[];
+
+  /**
+     * Optional. The id of the action called.
+     */
+  action_call_id?: string | undefined;
+}
+
+/**
+ * A named function to call.
+ */
+export interface FunctionCall {
+  /**
+     * Name of the function to call.
+     */
+  name?: string;
+
+  /**
+     * Optional. Arguments to pass to the function. Must be deserialized.
+     */
+  arguments?: string;
+}
+
+export type MessageContentParts = TextContentPart | ImageContentPart
+
+export interface TextContentPart {
+  /**
+     * Type of the message content. Should always be 'text'.
+     */
+  type: 'text';
+
+  /**
+     * The text of the message.
+     */
+  text: string;
+}
+
+export interface ImageContentPart {
+  /**
+     * Type of the message content. Should always be 'image_url'.
+     */
+  type: 'image_url';
+
+  /**
+     * The URL of the image.
+     */
+  image_url: string | { url: string };
+}
+
+/**
+ * Citations returned by the model.
+ */
+export interface Citation {
+  /**
+     * The content of the citation.
+     */
+  content: string;
+
+  /**
+     * The title of the citation.
+     */
+  title: string | null;
+
+  /**
+     * The URL of the citation.
+     */
+  url: string | null;
+
+  /**
+     * The filepath of the document.
+     */
+  filepath: string | null;
+}
+
+export interface MessageContext {
+  /**
+     * Citations used in the message.
+     */
+  citations: Citation[];
+
+  /**
+     * The intent of the message (what the user wrote).
+     */
+  intent: string;
+}

package/src/app/streaming/sensitivityUsageInfo.ts

@@ -0,0 +1,48 @@
+/**
+ * Sensitivity usage info for content sent to the user. This is used to provide information about the content to the user. See ClientCitation for more information.
+ */
+export interface SensitivityUsageInfo {
+  /**
+     * Must be "https://schema.org/Message"
+     */
+  type: 'https://schema.org/Message';
+
+  /**
+     * Required; Set to CreativeWork;
+     */
+  '@type': 'CreativeWork';
+
+  /**
+     * Sensitivity description of the content
+     */
+  description?: string;
+
+  /**
+     * Sensitivity title of the content
+     */
+  name: string;
+
+  /**
+     * Optional; ignored in Teams.
+     */
+  position?: number;
+
+  pattern?: {
+    /**
+         * Set to DefinedTerm
+         */
+    '@type': 'DefinedTerm';
+
+    inDefinedTermSet: string;
+
+    /**
+         * Color
+         */
+    name: string;
+
+    /**
+         * e.g. #454545
+         */
+    termCode: string;
+  };
+}