@microsoft/agents-hosting-dialogs 0.1.49

package/src/dialogHelper.ts

@@ -0,0 +1,154 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+  Activity,
+  ActivityTypes,
+  AgentStatePropertyAccessor,
+  TurnContext
+} from '@microsoft/agents-hosting'
+import { Dialog } from './dialog'
+import { DialogContext, DialogState } from './dialogContext'
+import { DialogEvents } from './dialogEvents'
+import { DialogSet } from './dialogSet'
+import { DialogStateManager, DialogStateManagerConfiguration } from './memory'
+import { DialogTurnResult } from './dialogTurnResult'
+import { DialogTurnStatus } from './dialogTurnStatus'
+
+/**
+ * Runs a dialog from a given context and accessor.
+ *
+ * @param dialog The Dialog to run.
+ * @param context TurnContext object for the current turn of conversation with the user.
+ * @param accessor Defined methods for accessing the state property created in a State object.
+ */
+export async function runDialog (
+  dialog: Dialog,
+  context: TurnContext,
+  accessor: AgentStatePropertyAccessor<DialogState>
+): Promise<void> {
+  if (!dialog) {
+    throw new Error('runDialog(): missing dialog')
+  }
+
+  if (!context) {
+    throw new Error('runDialog(): missing context')
+  }
+
+  if (!context.activity) {
+    throw new Error('runDialog(): missing context.activity')
+  }
+
+  if (!accessor) {
+    throw new Error('runDialog(): missing accessor')
+  }
+
+  const dialogSet = new DialogSet(accessor)
+  dialogSet.add(dialog)
+
+  const dialogContext = await dialogSet.createContext(context)
+
+  await internalRun(context, dialog.id, dialogContext)
+}
+
+/**
+ * @param context The TurnContext for the turn.
+ * @param dialogId The dialog ID.
+ * @param dialogContext The DialogContext for the current turn of conversation.
+ * @param dialogStateManagerConfiguration Configuration for the dialog state manager.
+ * @returns {Promise<DialogTurnResult>} a promise resolving to the dialog turn result.
+ */
+export async function internalRun (
+  context: TurnContext,
+  dialogId: string,
+  dialogContext: DialogContext,
+  dialogStateManagerConfiguration?: DialogStateManagerConfiguration
+): Promise<DialogTurnResult> {
+  // map TurnState into root dialog context.services
+  context.turnState.forEach((service, key) => {
+    dialogContext.services.push(key, service)
+  })
+
+  const dialogStateManager = new DialogStateManager(dialogContext, dialogStateManagerConfiguration)
+
+  await dialogStateManager.loadAllScopes()
+  dialogContext.context.turnState.push('DialogStateManager', dialogStateManager)
+  let dialogTurnResult: DialogTurnResult = null
+
+  // Loop as long as we are getting valid OnError handled we should continue executing the actions for the turn.
+  // NOTE: We loop around this block because each pass through we either complete the turn and break out of the loop
+  // or we have had an exception AND there was an OnError action which captured the error. We need to continue the
+  // turn based on the actions the OnError handler introduced.
+  let endOfTurn = false
+  while (!endOfTurn) {
+    try {
+      dialogTurnResult = await innerRun(context, dialogId, dialogContext)
+
+      // turn successfully completed, break the loop
+      endOfTurn = true
+    } catch (err) {
+      // fire error event, bubbling from the leaf.
+      const handled = await dialogContext.emitEvent(DialogEvents.error, err, true, true)
+
+      if (!handled) {
+        // error was NOT handled, throw the exception and end the turn.
+        // (This will trigger the Adapter.OnError handler and end the entire dialog stack)
+        throw err
+      }
+    }
+  }
+
+  // save all state scopes to their respective agentState locations.
+  await dialogStateManager.saveAllChanges()
+
+  // return the redundant result because the DialogManager contract expects it
+  return dialogTurnResult
+}
+
+async function innerRun (
+  context: TurnContext,
+  dialogId: string,
+  dialogContext: DialogContext
+): Promise<DialogTurnResult> {
+  // Continue or start the dialog.
+  let result = await dialogContext.continueDialog()
+  if (result.status === DialogTurnStatus.empty) {
+    result = await dialogContext.beginDialog(dialogId)
+  }
+
+  await sendStateSnapshotTrace(dialogContext)
+
+  return result
+}
+
+/**
+ * Recursively walk up the dialog context stack to find the active DC.
+ *
+ * @param dialogContext DialogContext for the current turn of conversation with the user.
+ * @returns Active DialogContext.
+ */
+export function getActiveDialogContext (dialogContext: DialogContext): DialogContext {
+  const child = dialogContext.child
+  if (!child) {
+    return dialogContext
+  }
+
+  return getActiveDialogContext(child)
+}
+
+// Helper to send a trace activity with a memory snapshot of the active dialog DC.
+const sendStateSnapshotTrace = async (dialogContext: DialogContext): Promise<void> => {
+  const traceLabel = 'Agent State'
+
+  // Send trace of memory
+  const snapshot = getActiveDialogContext(dialogContext).state.getMemorySnapshot()
+  const traceActivity = new Activity(ActivityTypes.Trace)
+  traceActivity.name = 'AgentState'
+  traceActivity.label = 'https://www.botframework.com/schemas/botState'
+  traceActivity.value = snapshot
+  traceActivity.label = traceLabel
+
+  await dialogContext.context.sendActivity(traceActivity)
+}

package/src/dialogInstance.ts

@@ -0,0 +1,32 @@
+/**
+ * Contains state information for an instance of a dialog on the stack.
+ *
+ * @template T Optional. The type that represents state information for the dialog.
+ *
+ * @remarks
+ * This contains information for a specific instance of a dialog on a dialog stack.
+ * The dialog stack is associated with a specific dialog context and dialog set.
+ * Information about the dialog stack as a whole is persisted to storage using a dialog state object.
+ *
+ */
+export interface DialogInstance<T = any> {
+  /**
+       * ID of this dialog
+       *
+       * @remarks
+       * Dialog state is associated with a specific dialog set.
+       * This ID is the the dialog's Dialog.id within that dialog set.
+       *
+       */
+  id: string;
+
+  /**
+       * The state information for this instance of this dialog.
+       */
+  state: T;
+
+  /**
+       * Hash code used to detect that a dialog has changed since the curent instance was started.
+       */
+  version?: string;
+}

package/src/dialogManager.ts

@@ -0,0 +1,202 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+  TurnContext,
+  AgentState,
+  ConversationState,
+  UserState,
+  TurnContextStateCollection,
+} from '@microsoft/agents-hosting'
+import { AgentStateSet } from './agentStateSet'
+import { Configurable } from './configurable'
+import { DialogContainer } from './dialogContainer'
+import { DialogContext, DialogState } from './dialogContext'
+import { internalRun } from './dialogHelper'
+import { DialogSet } from './dialogSet'
+import { DialogTurnStateConstants } from './dialogTurnStateConstants'
+import { Dialog } from './dialog'
+import { DialogStateManagerConfiguration } from './memory'
+import { DialogTurnResult } from './dialogTurnResult'
+
+const LAST_ACCESS = '_lastAccess'
+const CONVERSATION_STATE = 'ConversationState'
+const USER_STATE = 'UserState'
+
+export interface DialogManagerResult {
+  turnResult: DialogTurnResult;
+}
+
+export interface DialogManagerConfiguration {
+  conversationState: AgentState;
+  rootDialog: Dialog;
+  userState?: UserState;
+  expireAfter?: number;
+  stateConfiguration?: DialogStateManagerConfiguration;
+}
+
+/**
+ * Class which runs the dialog system.
+ *
+ * @deprecated This class will be deprecated.
+ */
+export class DialogManager extends Configurable {
+  private _rootDialogId: string
+  private readonly _dialogStateProperty: string
+  private readonly _initialTurnState: TurnContextStateCollection = new TurnContextStateCollection()
+
+  /**
+     * Creates an instance of the DialogManager class.
+     *
+     * @param rootDialog Optional, root Dialog to use.
+     * @param dialogStateProperty Optional, alternate name for the dialogState property. (Default is "DialogStateProperty")
+     */
+  constructor (rootDialog?: Dialog, dialogStateProperty?: string) {
+    super()
+    if (rootDialog) {
+      this.rootDialog = rootDialog
+    }
+    this._dialogStateProperty = dialogStateProperty ?? 'DialogState'
+    this._initialTurnState.set(DialogTurnStateConstants.dialogManager, this)
+  }
+
+  conversationState: ConversationState
+  userState?: UserState
+
+  /**
+     * Values that will be copied to the `TurnContext.turnState` at the beginning of each turn.
+     *
+     * @returns The turn state collection.
+     */
+  get initialTurnState (): TurnContextStateCollection {
+    return this._initialTurnState
+  }
+
+  /**
+     * Root dialog to start from [onTurn()](#onturn) method.
+     */
+  set rootDialog (value: Dialog) {
+    this.dialogs = new DialogSet()
+    if (value) {
+      this._rootDialogId = value.id
+      this.dialogs.add(value)
+      this.registerContainerDialogs(this.rootDialog, false)
+    } else {
+      this._rootDialogId = undefined
+    }
+  }
+
+  /**
+     * Gets the root Dialog ID.
+     *
+     * @returns The root Dialog ID.
+     */
+  get rootDialog (): Dialog {
+    return this._rootDialogId ? this.dialogs.find(this._rootDialogId) : undefined
+  }
+
+  dialogs: DialogSet = new DialogSet()
+  stateConfiguration?: DialogStateManagerConfiguration
+  expireAfter?: number
+
+  /**
+     * Set configuration settings.
+     *
+     * @param config Configuration settings to apply.
+     * @returns The cofigured DialogManager context.
+     */
+  configure (config: Partial<DialogManagerConfiguration>): this {
+    return super.configure(config)
+  }
+
+  /**
+     * Runs dialog system in the context of a TurnContext.
+     *
+     * @param context TurnContext for the current turn of conversation with the user.
+     * @returns Result of running the logic against the activity.
+     */
+  async onTurn (context: TurnContext): Promise<DialogManagerResult> {
+    // Ensure properly configured
+    if (!this._rootDialogId) {
+      throw new Error("DialogManager.onTurn: the agent's 'rootDialog' has not been configured.")
+    }
+
+    // Copy initial turn state to context
+    this.initialTurnState.forEach((value, key): void => {
+      context.turnState.set(key, value)
+    })
+
+    const agentStateSet = new AgentStateSet()
+
+    if (!this.conversationState) {
+      this.conversationState = context.turnState.get(CONVERSATION_STATE)
+    } else {
+      context.turnState.set(CONVERSATION_STATE, this.conversationState)
+    }
+
+    if (!this.conversationState) {
+      throw new Error("DialogManager.onTurn: the agent's 'conversationState' has not been configured.")
+    }
+    agentStateSet.add(this.conversationState)
+
+    if (!this.userState) {
+      this.userState = context.turnState.get(USER_STATE)
+    } else {
+      context.turnState.set(USER_STATE, this.userState)
+    }
+
+    if (this.userState) {
+      agentStateSet.add(this.userState)
+    }
+
+    // Get last access
+    const lastAccessProperty = this.conversationState.createProperty(LAST_ACCESS)
+    const lastAccess = new Date(await lastAccessProperty.get(context, new Date().toISOString()))
+
+    // Check for expired conversation
+    const now = new Date()
+    if (this.expireAfter !== undefined && now.getTime() - lastAccess.getTime() >= this.expireAfter) {
+      // Clear conversation state
+      await this.conversationState.clear(context)
+    }
+
+    // Update last access time
+    await lastAccessProperty.set(context, lastAccess.toISOString())
+
+    // get dialog stack
+    const dialogsProperty = this.conversationState.createProperty(this._dialogStateProperty)
+    const dialogState: DialogState = await dialogsProperty.get(context, {})
+
+    // Create DialogContext
+    const dc = new DialogContext(this.dialogs, context, dialogState)
+
+    // Call the common dialog "continue/begin" execution pattern shared with the classic RunAsync extension method
+    const turnResult = await internalRun(context, this._rootDialogId, dc, this.stateConfiguration)
+
+    // Save agentState changes
+    await agentStateSet.saveAllChanges(dc.context, false)
+
+    return { turnResult }
+  }
+
+  // Recursively traverses the dialog tree and registers intances of `DialogContainer` in the `DialogSet`
+  // for this `DialogManager` instance.
+  private registerContainerDialogs (dialog: Dialog, registerRoot = true): void {
+    if (!(dialog instanceof DialogContainer)) {
+      return
+    }
+    const container = dialog
+    if (registerRoot) {
+      if (this.dialogs.getDialogs().find((dlg) => dlg === container)) {
+        return
+      }
+      this.dialogs.add(container)
+    }
+
+    container.dialogs.getDialogs().forEach((inner) => {
+      this.registerContainerDialogs(inner)
+    })
+  }
+}

package/src/dialogReason.ts

@@ -0,0 +1,40 @@
+/**
+ * Indicates why a dialog method is being called.
+ *
+ * @remarks
+ * Use a dialog context to control the dialogs in a dialog set. The dialog context will pass a reference to itself
+ * to the dialog method it calls. It also passes in the _reason_ why the specific method is being called.
+ *
+ */
+export enum DialogReason {
+  /**
+       * The dialog is being started from DialogContext.beginDialog or DialogContext.replaceDialog.
+       */
+  beginCalled = 'beginCalled',
+
+  /**
+       * The dialog is being continued from DialogContext.continueDialog.
+       */
+  continueCalled = 'continueCalled',
+
+  /**
+       * The dialog is being ended from DialogContext.endDialog.
+       */
+  endCalled = 'endCalled',
+
+  /**
+       * The dialog is being ended from DialogContext.replaceDialog.
+       */
+  replaceCalled = 'replaceCalled',
+
+  /**
+       * The dialog is being cancelled from DialogContext.cancelAllDialogs.
+       */
+  cancelCalled = 'cancelCalled',
+
+  /**
+       * A step in a WaterfallDialog is being called
+       * because the previous step in the waterfall dialog called WaterfallStepContext.next.
+       */
+  nextCalled = 'nextCalled',
+}

package/src/dialogSet.ts

@@ -0,0 +1,168 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import {
+  AgentStatePropertyAccessor,
+  TurnContext
+} from '@microsoft/agents-hosting'
+
+import { Dialog } from './dialog'
+import { DialogContext, DialogState } from './dialogContext'
+import { StringUtils } from './stringUtils'
+
+export interface DialogDependencies {
+  /**
+     * Returns a dialogs child dialog dependencies so they can be added to a containers dialog set.
+     */
+  getDependencies(): Dialog[];
+}
+
+/**
+ * A related set of dialogs that can all call each other.
+ *
+ * @remarks
+ * The constructor for the dialog set should be passed a state property that will be used to
+ * persist the dialog stack for the set:
+ *
+ * To interact with the sets dialogs you can call createcontext with the
+ * current `TurnContext`. That will create a `DialogContext` that can be used to start or continue
+ * execution of the sets dialogs:
+ *
+ */
+export class DialogSet {
+  private readonly dialogs: { [id: string]: Dialog } = {}
+  private readonly dialogState: AgentStatePropertyAccessor<DialogState>
+  private _version: string
+
+  /**
+     * Creates a new DialogSet instance.
+     *
+     * @remarks
+     * If the `dialogState` property is not passed in, calls to createcontext
+     * will return an error.  You will need to create a `DialogContext` for the set manually and
+     * pass in your own state object for persisting the sets dialog stack:
+     *
+     * @param dialogState (Optional) state property used to persist the sets dialog stack.
+     */
+  constructor (dialogState?: AgentStatePropertyAccessor<DialogState>) {
+    this.dialogState = dialogState
+  }
+
+  /**
+     * Returns a 32-bit hash of the all the `Dialog.version` values in the set.
+     *
+     * @returns A version that will change when any of the child dialogs version changes.
+     * @remarks
+     * This hash is persisted to state storage and used to detect changes to a dialog set.
+     */
+  getVersion (): string {
+    if (!this._version) {
+      let versions = ''
+      for (const id in this.dialogs) {
+        const v = this.dialogs[id].getVersion()
+        if (v) {
+          versions += `|${v}`
+        }
+      }
+      this._version = StringUtils.hash(versions)
+    }
+
+    return this._version
+  }
+
+  /**
+     * Adds a new dialog or prompt to the set.
+     *
+     * @remarks
+     * If the `Dialog.id` being added already exists in the set, the dialogs id will be updated to
+     * include a suffix which makes it unique. So adding 2 dialogs named "duplicate" to the set
+     * would result in the first one having an id of "duplicate" and the second one having an id
+     * of "duplicate2".
+     * @param dialog The dialog or prompt to add.
+     * If a telemetryClient is present on the dialog set, it will be added to each dialog.
+     * @returns The dialog set after the operation is complete.
+     */
+  add<T extends Dialog>(dialog: T): this {
+    if (!(dialog instanceof Dialog)) {
+      throw new Error('DialogSet.add(): Invalid dialog being added.')
+    }
+
+    // Ensure new version hash is computed
+    this._version = undefined
+
+    // Ensure dialogs ID is unique.
+    if (Object.prototype.hasOwnProperty.call(this.dialogs, dialog.id)) {
+      // If we are trying to add the same exact instance, it's not a name collision.
+      // No operation required since the instance is already in the dialog set.
+      if (this.dialogs[dialog.id] === dialog) {
+        return this
+      }
+
+      // If we are adding a new dialog with a conflicting name, add a suffix to avoid
+      // dialog name collisions.
+      let nextSuffix = 2
+
+      while (true) {
+        const suffixId = dialog.id + nextSuffix.toString()
+        if (!Object.prototype.hasOwnProperty.call(this.dialogs, suffixId)) {
+          dialog.id = suffixId
+          break
+        } else {
+          nextSuffix++
+        }
+      }
+    }
+
+    // Save dialog reference
+    this.dialogs[dialog.id] = dialog
+
+    // Automatically add any child dependencies the dialog might have
+    if (typeof (dialog as any as DialogDependencies).getDependencies === 'function') {
+      (dialog as any as DialogDependencies).getDependencies().forEach((child: Dialog): void => {
+        this.add(child)
+      })
+    }
+
+    return this
+  }
+
+  /**
+     * Creates a dialog context which can be used to work with the dialogs in the set.
+     *
+     * @param context Context for the current turn of conversation with the user.
+     * @returns A promise representing the asynchronous operation.
+     */
+  async createContext (context: TurnContext): Promise<DialogContext> {
+    if (!this.dialogState) {
+      throw new Error(
+        'DialogSet.createContext(): the dialog set was not bound to a stateProperty when constructed.'
+      )
+    }
+    const state: DialogState = await this.dialogState.get(context, { dialogStack: [] } as DialogState)
+
+    return new DialogContext(this, context, state)
+  }
+
+  /**
+     * Finds a dialog that was previously added to the set using add.
+     *
+     * @remarks
+     * This example finds a dialog named "greeting":
+     *
+     * @param dialogId ID of the dialog or prompt to lookup.
+     * @returns The dialog if found; otherwise undefined.
+     */
+  find (dialogId: string): Dialog | undefined {
+    return Object.prototype.hasOwnProperty.call(this.dialogs, dialogId) ? this.dialogs[dialogId] : undefined
+  }
+
+  /**
+     * Gets the Dialogs of the set.
+     *
+     * @returns {Dialog} An array of Dialog.
+     */
+  getDialogs (): Dialog[] {
+    return Object.values(this.dialogs)
+  }
+}

package/src/dialogTurnResult.ts

@@ -0,0 +1,37 @@
+import { DialogTurnStatus } from './dialogTurnStatus'
+
+/**
+ * Represents the result of a dialog context's attempt to begin, continue,
+ * or otherwise manipulate one or more dialogs.
+ *
+ * @template T Optional. The type that represents a result returned by the active dialog when it
+ *      successfully completes.
+ *
+ * @remarks
+ * This can be used to determine if a dialog completed and a result is available, or if the stack
+ * was initially empty and a dialog should be started.
+ *
+ */
+export interface DialogTurnResult<T = any> {
+  /**
+     * The state of the dialog stack after a dialog context's attempt.
+     */
+  status: DialogTurnStatus;
+
+  /**
+     * The result, if any, returned by the last dialog on the stack.
+     *
+     * @remarks
+     * A result value is available only if
+     * the stack is now empty,
+     * the last dialog on the stack completed normally,
+     * and the last dialog returned a result to the dialog context.
+     */
+  result?: T;
+
+  /**
+     * If true, a `DialogCommand` has ended its parent container and the parent should not perform
+     * any further processing.
+     */
+  parentEnded?: boolean;
+}

package/src/dialogTurnStateConstants.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Defines dialog turn state constants.
+ */
+export class DialogTurnStateConstants {
+  static configuration = Symbol('configuration')
+  static dialogManager = Symbol('dialogManager')
+  static queueStorage = Symbol('queueStorage')
+}

package/src/dialogTurnStatus.ts

@@ -0,0 +1,38 @@
+/**
+ * Represents the state of the dialog stack after a dialog context attempts to begin, continue,
+ * or otherwise manipulate one or more dialogs.
+ *
+ */
+export enum DialogTurnStatus {
+  /**
+     * The dialog stack is empty.
+     *
+     * @remarks
+     * Indicates that the dialog stack was initially empty when the operation was attempted.
+     */
+  empty = 'empty',
+
+  /**
+     * The active dialog on top of the stack is waiting for a response from the user.
+     */
+  waiting = 'waiting',
+
+  /**
+     * The last dialog on the stack completed successfully.
+     *
+     * @remarks
+     * Indicates that a result might be available and the stack is now empty.
+     *
+     */
+  complete = 'complete',
+
+  /**
+     * All dialogs on the stack were cancelled and the stack is empty.
+     */
+  cancelled = 'cancelled',
+
+  /**
+     * Current dialog completed successfully, but turn should end.
+     */
+  completeAndWait = 'completeAndWait',
+}