@microsoft/agents-hosting-dialogs 0.1.49

package/src/memory/scopes/settingsMemoryScope.ts

@@ -0,0 +1,239 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { DialogContext } from '../../dialogContext'
+import { DialogTurnStateConstants } from '../../dialogTurnStateConstants'
+import { MemoryScope } from './memoryScope'
+import { ScopePath } from '../scopePath'
+
+/**
+ * The setting node.
+ */
+class Node {
+  constructor (public value?: string) {}
+  children: Node[] = []
+  isLeaf (): boolean {
+    return this.children.length === 0
+  }
+}
+
+export class SettingsMemoryScope extends MemoryScope {
+  private static readonly blockingList = [
+    'MicrosoftAppPassword',
+    'cosmosDb:authKey',
+    'blobStorage:connectionString',
+    'BlobsStorage:connectionString',
+    'CosmosDbPartitionedStorage:authKey',
+    'applicationInsights:connectionString',
+    'applicationInsights:InstrumentationKey',
+    'runtimeSettings:telemetry:options:connectionString',
+    'runtimeSettings:telemetry:options:instrumentationKey',
+    'runtimeSettings:features:blobTranscript:connectionString',
+  ]
+
+  /**
+     * Initializes a new instance of the SettingsMemoryScope class.
+     *
+     * @param initialSettings initial set of settings to supply
+     */
+  constructor (private readonly initialSettings?: Record<string, unknown>) {
+    super(ScopePath.settings, false)
+  }
+
+  /**
+     * Gets the backing memory for this scope.
+     *
+     * @param {DialogContext} dialogContext The DialogContext object for this turn.
+     * @returns {Record<string, ?>} The memory for the scope.
+     */
+  getMemory (dialogContext: DialogContext): Record<string, unknown> {
+    if (dialogContext.context.turnState.has(ScopePath.settings)) {
+      return dialogContext.context.turnState.get(ScopePath.settings) ?? {}
+    }
+
+    const configuration = dialogContext.context.turnState.get(DialogTurnStateConstants.configuration) ?? {}
+
+    Object.entries(process.env).reduce((result, [key, value]) => {
+      result[`${key}`] = value
+      return result
+    }, configuration)
+
+    const settings = SettingsMemoryScope.loadSettings(configuration)
+    dialogContext.context.turnState.set(ScopePath.settings, settings)
+
+    return settings
+  }
+
+  /**
+     * @param dialogContext Current dialog context.
+     */
+  async load (dialogContext: DialogContext): Promise<void> {
+    if (this.initialSettings) {
+      // filter initialSettings
+      const filteredSettings = SettingsMemoryScope.filterSettings(this.initialSettings)
+      dialogContext.context.turnState.set(ScopePath.settings, filteredSettings)
+    }
+
+    await super.load(dialogContext)
+  }
+
+  /**
+     * Build a dictionary view of configuration providers.
+     *
+     * @param {Record<string, string>} configuration The configuration that we are running with.
+     * @returns {Record<string, ?>} Projected dictionary for settings.
+     */
+  protected static loadSettings (configuration: Record<string, string>): Record<string, unknown> {
+    let settings = {}
+
+    if (configuration) {
+      // load configuration into settings
+      const root = this.convertFlattenSettingToNode(Object.entries(configuration))
+      settings = root.children.reduce(
+        (acc, child) => ({ ...acc, [child.value ?? '']: this.convertNodeToObject(child) }),
+        settings
+      )
+    }
+
+    // filter env configuration settings
+    return this.filterSettings(settings)
+  }
+
+  /**
+     * Generate a node tree with the flatten settings.
+     * For example:
+     * {
+     *   "array":["item1", "item2"],
+     *   "object":{"array":["item1"], "2":"numberkey"}
+     * }
+     *
+     * Would generate a flatten settings like:
+     * array:0 item1
+     * array:1 item2
+     * object:array:0 item1
+     * object:2 numberkey
+     *
+     * After Converting it from flatten settings into node tree, would get:
+     *
+     *                         null
+     *                |                     |
+     *              array                object
+     *            |        |            |        |
+     *           0          1        array        2
+     *           |          |         |           |
+     *         item1       item2      0        numberkey
+     *                                |
+     *                              item1
+     * The result is a Tree.
+     *
+     * @param {Array<[string, string]>} kvs Configurations with key value pairs.
+     * @returns {Node} The root node of the tree.
+     */
+  private static convertFlattenSettingToNode (kvs: Array<[key: string, value: string]>): Node {
+    const root = new Node()
+
+    kvs.forEach(([key, value]) => {
+      const keyChain = key.split(':')
+      let currentNode = root
+      keyChain.forEach((item) => {
+        const matchItem = currentNode.children.find((u) => u?.value === item)
+        if (!matchItem) {
+          // Remove all the leaf children
+          currentNode.children = currentNode.children.filter((u) => u.children.length !== 0)
+
+          // Append new child into current node
+          const node = new Node(item)
+          currentNode.children.push(node)
+          currentNode = node
+        } else {
+          currentNode = matchItem
+        }
+      })
+
+      currentNode.children.push(new Node(value))
+    })
+
+    return root
+  }
+
+  private static convertNodeToObject (node: Node): unknown {
+    if (!node.children.length) {
+      return {}
+    }
+
+    // If the child is leaf node, return its value directly.
+    if (node.children.length === 1 && node.children[0].isLeaf()) {
+      return node.children[0].value
+    }
+
+    // check if all the children are number format.
+    let pureNumberIndex = true
+    const indexArray: number[] = []
+    let indexMax = -1
+    for (let i = 0; i < node.children.length; i++) {
+      const child = node.children[Number(i)]
+      if (child.value && /^-?\d+$/.test(child.value)) {
+        const num = parseInt(child.value, 10)
+        if (!isNaN(num) && num >= 0) {
+          indexArray.push(num)
+          if (num > indexMax) {
+            indexMax = num
+          }
+          continue
+        }
+      }
+      pureNumberIndex = false
+      break
+    }
+
+    if (pureNumberIndex) {
+      // all children are int numbers, treat it as array.
+      const listResult = new Array(indexMax + 1)
+      node.children.forEach((child, index) => {
+        listResult[indexArray[Number(index)]] = this.convertNodeToObject(child)
+      })
+      return listResult
+    }
+
+    // Convert all child into dictionary
+    return node.children.reduce((result: Record<string, any>, child: Node) => {
+      if (child.value) {
+        result[child.value] = this.convertNodeToObject(child)
+      }
+      return result
+    }, {})
+  }
+
+  private static filterSettings (settings: Record<string, unknown>): Record<string, unknown> {
+    const result = Object.assign({}, settings)
+    this.blockingList.forEach((path) => this.deletePropertyPath(result, path))
+    return result
+  }
+
+  private static deletePropertyPath (obj: Record<string, any>, path: string): void {
+    if (!obj || !path?.length) {
+      return
+    }
+
+    const pathArray = path.split(':')
+
+    for (let i = 0; i < pathArray.length - 1; i++) {
+      const realKey = Object.keys(obj).find((key) => key.toLowerCase() === pathArray[i].toLowerCase())
+      if (realKey) {
+        obj = obj[realKey]
+      }
+
+      if (!obj) {
+        return
+      }
+    }
+
+    const lastPath = pathArray.pop()?.toLowerCase()
+    const lastKey = Object.keys(obj).find((key) => key.toLowerCase() === lastPath)
+    if (lastKey) {
+      delete obj[lastKey]
+    }
+  }
+}

package/src/memory/scopes/thisMemoryScope.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { MemoryScope } from './memoryScope'
+import { ScopePath } from '../scopePath'
+import { DialogContext } from '../../dialogContext'
+
+export class ThisMemoryScope extends MemoryScope {
+  /**
+     * Initializes a new instance of the ThisMemoryScope class.
+     */
+  constructor () {
+    super(ScopePath.this)
+  }
+
+  /**
+     * Gets the backing memory for this scope.
+     *
+     * @param dialogContext The DialogContext object for this turn.
+     * @returns The memory for the scope.
+     */
+  getMemory (dialogContext: DialogContext): object {
+    return dialogContext.activeDialog ? dialogContext.activeDialog.state : {}
+  }
+
+  /**
+     * Changes the backing object for the memory scope.
+     *
+     * @param dialogContext The DialogContext object for this turn.
+     * @param memory Memory object to set for the scope.
+     */
+  setMemory (dialogContext: DialogContext, memory: object): void {
+    if (memory === undefined) {
+      throw new Error('ThisMemoryScope.setMemory: undefined memory object passed in.')
+    }
+
+    if (!dialogContext.activeDialog) {
+      throw new Error('ThisMemoryScope.setMemory: no active dialog found.')
+    }
+
+    dialogContext.activeDialog.state = memory
+  }
+}

package/src/memory/scopes/turnMemoryScope.ts

@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { MemoryScope } from './memoryScope'
+import { ScopePath } from '../scopePath'
+import { DialogContext } from '../../dialogContext'
+
+/**
+ * @private
+ */
+const TURN_STATE = 'turn'
+
+/**
+ * TurnMemoryScope represents memory scoped to the current turn.
+ */
+export class TurnMemoryScope extends MemoryScope {
+  /**
+     * Initializes a new instance of the TurnMemoryScope class.
+     */
+  constructor () {
+    super(ScopePath.turn, true)
+  }
+
+  /**
+     * Get the backing memory for this scope.
+     *
+     * @param dialogContext The DialogContext for this turn.
+     * @returns The memory for the scope.
+     */
+  getMemory (dialogContext: DialogContext): object {
+    let memory = dialogContext.context.turnState.get(TURN_STATE)
+    if (typeof memory !== 'object') {
+      memory = {}
+      dialogContext.context.turnState.set(TURN_STATE, memory)
+    }
+
+    return memory
+  }
+
+  /**
+     * Changes the backing object for the memory scope.
+     *
+     * @param dialogContext The DialogContext for this turn.
+     * @param memory Memory object to set for the scope.
+     */
+  setMemory (dialogContext: DialogContext, memory: object): void {
+    if (memory === undefined) {
+      throw new Error('TurnMemoryScope.setMemory: undefined memory object passed in.')
+    }
+
+    dialogContext.context.turnState.set(TURN_STATE, memory)
+  }
+}

package/src/memory/scopes/userMemoryScope.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { AgentStateMemoryScope } from './agentStateMemoryScope'
+import { ScopePath } from '../scopePath'
+
+/**
+ * Memory that's scoped to the current user.
+ */
+export class UserMemoryScope extends AgentStateMemoryScope {
+  protected stateKey = 'UserState'
+  /**
+     * Initializes a new instance of the UserMemoryScope class.
+     */
+  constructor () {
+    super(ScopePath.user)
+  }
+}

package/src/memory/turnPath.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Defines path for avaiable turns.
+ */
+export class TurnPath {
+  /// The result from the last dialog that was called.
+  static readonly lastResult = 'turn.lastresult'
+
+  /// The current activity for the turn.
+  static readonly activity = 'turn.activity'
+
+  /// The recognized result for the current turn.
+  static readonly recognized = 'turn.recognized'
+
+  /// Path to the top intent.
+  static readonly topIntent = 'turn.recognized.intent'
+
+  /// Path to the top score.
+  static readonly topScore = 'turn.recognized.score'
+
+  /// Original text.
+  static readonly text = 'turn.recognized.text'
+
+  /// Original utterance split into unrecognized strings.
+  static readonly unrecognizedText = 'turn.unrecognizedText'
+
+  /// Entities that were recognized from text.
+  static readonly recognizedEntities = 'turn.recognizedEntities'
+
+  /// If true an interruption has occured.
+  static readonly interrupted = 'turn.interrupted'
+
+  /// The current dialog event (set during event processings).
+  static readonly dialogEvent = 'turn.dialogEvent'
+
+  /// Used to track that we don't end up in infinite loop of RepeatDialogs().
+  static readonly repeatedIds = 'turn.repeatedIds'
+
+  /// This is a bool which if set means that the turncontext.activity has been consumed by some component in the system.
+  static readonly activityProcessed = 'turn.activityProcessed'
+}

package/src/prompts/activityPrompt.ts

@@ -0,0 +1,202 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { Activity, InputHints, TurnContext, ActivityTypes } from '@microsoft/agents-hosting'
+import { Dialog } from '../dialog'
+import { DialogContext } from '../dialogContext'
+import { PromptOptions, PromptRecognizerResult, PromptValidator } from './prompt'
+import { DialogInstance } from '../dialogInstance'
+import { DialogReason } from '../dialogReason'
+import { DialogTurnResult } from '../dialogTurnResult'
+
+/**
+ * Waits for an activity to be received.
+ *
+ * @remarks
+ * This prompt requires a validator be passed in and is useful when waiting for non-message
+ * activities like an event to be received. The validator can ignore received events until the
+ * expected activity is received.
+ */
+export class ActivityPrompt extends Dialog {
+  /**
+     * Creates a new ActivityPrompt instance.
+     *
+     * @param dialogId Unique ID of the dialog within its parent `DialogSet` or `ComponentDialog`.
+     * @param validator Validator that will be called each time a new activity is received.
+     */
+  constructor (
+    dialogId: string,
+    private validator: PromptValidator<Activity>
+  ) {
+    super(dialogId)
+  }
+
+  /**
+     * Called when a prompt dialog is pushed onto the dialog stack and is being activated.
+     *
+     * @param dialogContext The DialogContext for the current
+     * turn of the conversation.
+     * @param options PromptOptions, additional
+     * information to pass to the prompt being started.
+     * @returns A `Promise` representing the asynchronous operation.
+     * @remarks
+     * If the promise is successful, the result indicates whether the prompt is still
+     * active after the turn has been processed by the prompt.
+     */
+  async beginDialog (dialogContext: DialogContext, options: PromptOptions): Promise<DialogTurnResult> {
+    // Ensure prompts have input hint set
+    const opt: Partial<PromptOptions> = { ...options }
+    if (opt.prompt && typeof opt.prompt === 'object' && typeof opt.prompt.inputHint !== 'string') {
+      opt.prompt.inputHint = InputHints.ExpectingInput
+    }
+    if (opt.retryPrompt && typeof opt.retryPrompt === 'object' && typeof opt.retryPrompt.inputHint !== 'string') {
+      opt.retryPrompt.inputHint = InputHints.ExpectingInput
+    }
+
+    // Initialize prompt state
+    const state: any = dialogContext.activeDialog.state as ActivityPromptState
+    state.options = opt
+    state.state = {}
+
+    // Send initial prompt
+    await this.onPrompt(dialogContext.context, state.state, state.options, false)
+
+    return Dialog.EndOfTurn
+  }
+
+  /**
+     * Called when a prompt dialog is the active dialog and the user replied with a new activity.
+     *
+     * @param dialogContext The DialogContext for the current
+     * turn of conversation.
+     * @returns A `Promise` representing the asynchronous operation.
+     * @remarks
+     * If the promise is successful, the result indicates whether the dialog is still
+     * active after the turn has been processed by the dialog.
+     * The prompt generally continues to receive the user's replies until it accepts the
+     * user's reply as valid input for the prompt.
+     */
+  async continueDialog (dialogContext: DialogContext): Promise<DialogTurnResult> {
+    // Perform base recognition
+    const state: any = dialogContext.activeDialog.state as ActivityPromptState
+    const recognized: PromptRecognizerResult<Activity> = await this.onRecognize(
+      dialogContext.context,
+      state.state,
+      state.options
+    )
+
+    if (state.state['attemptCount'] === undefined) {
+      state.state['attemptCount'] = 0
+    }
+
+    // Validate the return value
+    // - Unlike the other prompts a validator is required for an ActivityPrompt so we don't
+    //   need to check for its existence before calling it.
+    const isValid: boolean = await this.validator({
+      context: dialogContext.context,
+      recognized,
+      state: state.state,
+      options: state.options,
+      attemptCount: ++state.state['attemptCount'],
+    })
+
+    // Return recognized value or re-prompt
+    if (isValid) {
+      return await dialogContext.endDialog(recognized.value)
+    } else {
+      if (dialogContext.context.activity.type === ActivityTypes.Message && !dialogContext.context.responded) {
+        await this.onPrompt(dialogContext.context, state.state, state.options, true)
+      }
+
+      return Dialog.EndOfTurn
+    }
+  }
+
+  /**
+     * Called when a prompt dialog resumes being the active dialog on the dialog stack, such as
+     * when the previous active dialog on the stack completes.
+     *
+     * @param dialogContext The DialogContext for the current turn
+     * of the conversation.
+     * @param _reason DialogReason, an enum indicating why
+     * the dialog resumed.
+     * @param _result Optional. Value returned from the previous dialog on the stack.
+     * The type of the value returned is dependent on the previous dialog.
+     * @returns A `Promise` representing the asynchronous operation.
+     */
+  async resumeDialog (dialogContext: DialogContext, _reason: DialogReason, _result?: any): Promise<DialogTurnResult> {
+    // Prompts are typically leaf nodes on the stack but the dev is free to push other dialogs
+    // on top of the stack which will result in the prompt receiving an unexpected call to
+    // resumeDialog() when the pushed on dialog ends.
+    // To avoid the prompt prematurely ending we need to implement this method and
+    // simply re-prompt the user.
+    await this.repromptDialog(dialogContext.context, dialogContext.activeDialog)
+
+    return Dialog.EndOfTurn
+  }
+
+  /**
+     * Called when a prompt dialog has been requested to re-prompt the user for input.
+     *
+     * @param context TurnContext, context for the current
+     * turn of conversation with the user.
+     * @param instance DialogInstance, the instance
+     * of the dialog on the stack.
+     * @returns A `Promise` representing the asynchronous operation.
+     */
+  async repromptDialog (context: TurnContext, instance: DialogInstance): Promise<void> {
+    const state: ActivityPromptState = instance.state as ActivityPromptState
+    await this.onPrompt(context, state.state, state.options, false)
+  }
+
+  /**
+     * When overridden in a derived class, prompts the user for input.
+     *
+     * @param context TurnContext, context for the current
+     * turn of conversation with the user.
+     * @param state Contains state for the current instance of the prompt on the dialog stack.
+     * @param options A PromptOptions object constructed
+     * from the options initially provided in the call to Prompt.
+     * @param isRetry A boolean representing if the prompt is a retry.
+     * @returns A `Promise` representing the asynchronous operation.
+     */
+  protected async onPrompt (
+    context: TurnContext,
+    state: object,
+    options: PromptOptions,
+    isRetry: boolean
+  ): Promise<void> {
+    if (isRetry && options.retryPrompt) {
+      await context.sendActivity(options.retryPrompt, undefined, InputHints.ExpectingInput)
+    } else if (options.prompt) {
+      await context.sendActivity(options.prompt, undefined, InputHints.ExpectingInput)
+    }
+  }
+
+  /**
+     * When overridden in a derived class, attempts to recognize the incoming Activity.
+     *
+     * @param context TurnContext, context for the current
+     * turn of conversation with the user.
+     * @param _state Contains state for the current instance of the prompt on the dialog stack.
+     * @param _options A PromptOptions object constructed
+     * from the options initially provided in the call to Prompt.
+     * @returns A `Promise` representing the asynchronous operation.
+     */
+  protected async onRecognize (
+    context: TurnContext,
+    _state: object,
+    _options: PromptOptions
+  ): Promise<PromptRecognizerResult<Activity>> {
+    return { succeeded: true, value: context.activity }
+  }
+}
+
+/**
+ * @private
+ */
+interface ActivityPromptState {
+  state: object;
+  options: PromptOptions;
+}

package/src/prompts/attachmentPrompt.ts

@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { Attachment, InputHints, TurnContext } from '@microsoft/agents-hosting'
+import { Prompt, PromptOptions, PromptRecognizerResult, PromptValidator } from './prompt'
+
+/**
+ * Prompts a user to upload attachments like images.
+ *
+ * @remarks
+ * By default the prompt will return to the calling dialog an `Attachment[]`.
+ */
+export class AttachmentPrompt extends Prompt<Attachment[]> {
+  // eslint-disable-next-line @typescript-eslint/no-useless-constructor
+  constructor (dialogId: string, validator?: PromptValidator<Attachment[]>) {
+    super(dialogId, validator)
+  }
+
+  /**
+     * Prompts the user for input.
+     *
+     * @param context Context for the current turn of conversation with the user.
+     * @param state Contains state for the current instance of the prompt on the dialog stack.
+     * @param options A prompt options object constructed from the options initially provided
+     * in the call to Prompt.
+     * @param isRetry `true` if this is the first time this prompt dialog instance
+     * on the stack is prompting the user for input; otherwise, false.
+     * @returns A Promise representing the asynchronous operation.
+     */
+  protected async onPrompt (
+    context: TurnContext,
+    state: any,
+    options: PromptOptions,
+    isRetry: boolean
+  ): Promise<void> {
+    if (isRetry && options.retryPrompt) {
+      await context.sendActivity(options.retryPrompt, undefined, InputHints.ExpectingInput)
+    } else if (options.prompt) {
+      await context.sendActivity(options.prompt, undefined, InputHints.ExpectingInput)
+    }
+  }
+
+  /**
+     * Attempts to recognize the user's input.
+     *
+     * @param context Context for the current turn of conversation with the user.
+     * @param _state Contains state for the current instance of the prompt on the dialog stack.
+     * @param _options A prompt options object constructed from the options initially provided
+     * in the call to Prompt.
+     * @returns A Promise representing the asynchronous operation.
+     */
+  protected async onRecognize (
+    context: TurnContext,
+    _state: any,
+    _options: PromptOptions
+  ): Promise<PromptRecognizerResult<Attachment[]>> {
+    const value: Attachment[] = context.activity.attachments
+
+    return Array.isArray(value) && value.length > 0 ? { succeeded: true, value } : { succeeded: false }
+  }
+}