@microsoft/agents-hosting-dialogs 1.1.4-g8d884129e7 → 1.2.0-alpha.18.g3c104e426a

package/src/errorHelper.ts

@@ -0,0 +1,263 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { AgentErrorDefinition } from '@microsoft/agents-activity'
+
+/**
+ * Error definitions for the Dialogs system.
+ * This contains localized error codes for the Dialogs subsystem of the AgentSDK.
+ *
+ * Each error definition includes an error code (starting from -130000), a description, and a help link
+ * pointing to an AKA link to get help for the given error.
+ *
+ * Usage example:
+ * ```
+ * throw ExceptionHelper.generateException(
+ *   Error,
+ *   Errors.MissingDialog
+ * );
+ * ```
+ */
+export const Errors: { [key: string]: AgentErrorDefinition } = {
+  // Dialog Helper Errors (-130000 to -130003)
+  /**
+   * Error thrown when dialog parameter is missing.
+   */
+  MissingDialog: {
+    code: -130000,
+    description: 'runDialog(): missing dialog'
+  },
+
+  /**
+   * Error thrown when context parameter is missing.
+   */
+  MissingContext: {
+    code: -130001,
+    description: 'runDialog(): missing context'
+  },
+
+  /**
+   * Error thrown when context.activity is missing.
+   */
+  MissingContextActivity: {
+    code: -130002,
+    description: 'runDialog(): missing context.activity'
+  },
+
+  /**
+   * Error thrown when accessor parameter is missing.
+   */
+  MissingAccessor: {
+    code: -130003,
+    description: 'runDialog(): missing accessor'
+  },
+
+  // Dialog Manager Errors (-130004 to -130005)
+  /**
+   * Error thrown when root dialog has not been configured.
+   */
+  RootDialogNotConfigured: {
+    code: -130004,
+    description: "DialogManager.onTurn: the agent's 'rootDialog' has not been configured.",
+  },
+
+  /**
+   * Error thrown when conversationState has not been configured.
+   */
+  ConversationStateNotConfigured: {
+    code: -130005,
+    description: "DialogManager.onTurn: the agent's 'conversationState' has not been configured.",
+  },
+
+  // Recognizer Errors (-130006 to -130007)
+  /**
+   * Error thrown when recognizer result is empty.
+   */
+  EmptyRecognizerResult: {
+    code: -130006,
+    description: 'result is empty'
+  },
+
+  /**
+   * Error thrown when recognize function is not implemented.
+   */
+  RecognizeFunctionNotImplemented: {
+    code: -130007,
+    description: 'Please implement recognize function.'
+  },
+
+  // Dialog State Manager Errors (-130008 to -130013)
+  /**
+   * Error thrown when path is not specified in setValue.
+   */
+  PathNotSpecified: {
+    code: -130008,
+    description: "DialogStateManager.setValue: path wasn't specified.",
+  },
+
+  /**
+   * Error thrown when memory scope is not found in setValue.
+   */
+  ScopeNotFound: {
+    code: -130009,
+    description: "DialogStateManager.setValue: a scope of '{scope}' wasn't found.",
+  },
+
+  /**
+   * Error thrown when unable to update value with negative index.
+   */
+  NegativeIndexNotAllowed: {
+    code: -130010,
+    description: "DialogStateManager.setValue: unable to update value for '{path}'. Negative indexes aren't allowed.",
+  },
+
+  /**
+   * Error thrown when unable to update value for path.
+   */
+  UnableToUpdateValue: {
+    code: -130011,
+    description: "DialogStateManager.setValue: unable to update value for '{path}'.",
+  },
+
+  /**
+   * Error thrown when invalid path in deleteValue.
+   */
+  InvalidDeletePath: {
+    code: -130012,
+    description: "DialogStateManager.deleteValue: invalid path of '{path}'.",
+  },
+
+  /**
+   * Error thrown when scope not found in deleteValue.
+   */
+  ScopeNotFoundForDelete: {
+    code: -130013,
+    description: "DialogStateManager.deleteValue: a scope of '{scope}' wasn't found.",
+  },
+
+  /**
+   * Error thrown when path contains invalid characters.
+   */
+  InvalidPathCharacters: {
+    code: -130014,
+    description: "DialogStateManager: path '{path}' contains invalid characters.",
+  },
+
+  /**
+   * Error thrown when path resolution fails.
+   */
+  PathResolutionFailed: {
+    code: -130015,
+    description: "DialogStateManager: unable to resolve path '{path}'.",
+  },
+
+  // Dialog Set Errors (-130016 to -130017)
+  /**
+   * Error thrown when invalid dialog is being added to DialogSet.
+   */
+  InvalidDialogBeingAdded: {
+    code: -130016,
+    description: 'DialogSet.add(): Invalid dialog being added.'
+  },
+
+  /**
+   * Error thrown when DialogSet was not bound to a stateProperty.
+   */
+  DialogSetNotBound: {
+    code: -130017,
+    description: 'DialogSet.createContext(): the dialog set was not bound to a stateProperty when constructed.'
+  },
+
+  // Dialog Context Error Errors (-130018 to -130019)
+  /**
+   * Error thrown when error argument is not an Error or string.
+   */
+  InvalidErrorArgument: {
+    code: -130018,
+    description: '`error` argument must be an Error or a string'
+  },
+
+  /**
+   * Error thrown when dialogContext argument is not of type DialogContext.
+   */
+  InvalidDialogContextArgument: {
+    code: -130019,
+    description: '`dialogContext` argument must be of type DialogContext'
+  },
+
+  // Dialog Errors (-130020)
+  /**
+   * Error thrown when onComputeId is not implemented.
+   */
+  OnComputeIdNotImplemented: {
+    code: -130020,
+    description: 'Dialog.onComputeId(): not implemented.'
+  },
+
+  // Agent State Set Errors (-130021)
+  /**
+   * Error thrown when non-AgentState object is added to AgentStateSet.
+   */
+  InvalidAgentStateObject: {
+    code: -130021,
+    description: "AgentStateSet: a object was added that isn't an instance of AgentStateSet.",
+  },
+
+  // Memory Scope Errors (-130022 to -130029)
+  /**
+   * Error thrown when state key is not available in memory scope.
+   */
+  StateKeyNotAvailable: {
+    code: -130022,
+    description: '{stateKey} is not available.'
+  },
+
+  /**
+   * Error thrown when attempting to replace root AgentState object.
+   */
+  CannotReplaceRootAgentState: {
+    code: -130023,
+    description: 'You cannot replace the root AgentState object.'
+  },
+
+  /**
+   * Error thrown when undefined memory object passed to setMemory.
+   */
+  UndefinedMemoryObject: {
+    code: -130024,
+    description: '{scopeName}.setMemory: undefined memory object passed in.'
+  },
+
+  /**
+   * Error thrown when activeDialog is undefined.
+   */
+  ActiveDialogUndefined: {
+    code: -130025,
+    description: 'DialogMemoryScope: activeDialog is undefined.'
+  },
+
+  /**
+   * Error thrown when memory scope operation is not supported.
+   */
+  MemoryScopeOperationNotSupported: {
+    code: -130026,
+    description: '{scopeName}: {operation} is not supported.'
+  },
+
+  /**
+   * Error thrown when attempting unsupported memory scope operation.
+   */
+  UnsupportedMemoryScopeOperation: {
+    code: -130027,
+    description: 'MemoryScope.{operation}(): operation not supported for this scope.'
+  },
+
+  // Waterfall Dialog Errors (-130028)
+  /**
+   * Error thrown when waterfall step error occurs.
+   */
+  WaterfallStepError: {
+    code: -130028,
+    description: 'WaterfallDialog: error in step {stepIndex}.'
+  }
+}

package/src/index.ts

@@ -32,6 +32,7 @@ export { Configuration } from './configuration'
 export * from './intentScore'
 
 export { runDialog } from './dialogHelper'
+export { Errors as DialogErrors } from './errorHelper'
 
 // Type-only re-export to avoid TypeDoc issues
 export type { TurnContext } from '@microsoft/agents-hosting'

package/src/memory/dialogStateManager.ts

@@ -6,6 +6,8 @@
 import { ComponentMemoryScopes, isComponentMemoryScopes } from './componentMemoryScopes'
 import { ComponentPathResolvers, isComponentPathResolvers } from './componentPathResolvers'
 import { ComponentRegistration } from '../componentRegistration'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../errorHelper'
 import { DialogContext } from '../dialogContext'
 import { DialogPath } from './dialogPath'
 import { DialogsComponentRegistration } from '../dialogsComponentRegistration'
@@ -176,7 +178,10 @@ export class DialogStateManager {
     const tpath = this.transformPath(pathExpression)
     const segments = this.parsePath(tpath)
     if (segments.length < 1) {
-      throw new Error("DialogStateManager.setValue: path wasn't specified.")
+      throw ExceptionHelper.generateException(
+        Error,
+        Errors.PathNotSpecified
+      )
     }
 
     // Track changes
@@ -185,7 +190,12 @@ export class DialogStateManager {
     // Get memory scope to update
     const scope = this.getMemoryScope(segments[0].toString())
     if (scope === undefined) {
-      throw new Error(`DialogStateManager.setValue: a scope of '${segments[0]}' wasn't found.`)
+      throw ExceptionHelper.generateException(
+        Error,
+        Errors.ScopeNotFound,
+        undefined,
+        { scope: segments[0].toString() }
+      )
     }
 
     // Update memory
@@ -203,8 +213,11 @@ export class DialogStateManager {
       if (typeof key === 'number' && Array.isArray(memory)) {
         // Only allow positive indexes
         if (key < 0) {
-          throw new Error(
-                        `DialogStateManager.setValue: unable to update value for '${pathExpression}'. Negative indexes aren't allowed.`
+          throw ExceptionHelper.generateException(
+            Error,
+            Errors.NegativeIndexNotAllowed,
+            undefined,
+            { path: pathExpression }
           )
         }
 
@@ -224,7 +237,12 @@ export class DialogStateManager {
         key = this.findObjectKey(memory, key) || key
         memory[key] = value
       } else {
-        throw new Error(`DialogStateManager.setValue: unable to update value for '${pathExpression}'.`)
+        throw ExceptionHelper.generateException(
+          Error,
+          Errors.UnableToUpdateValue,
+          undefined,
+          { path: pathExpression }
+        )
       }
     } else {
       // Just update memory scope
@@ -242,7 +260,12 @@ export class DialogStateManager {
     const tpath = this.transformPath(pathExpression)
     const segments = this.parsePath(tpath)
     if (segments.length < 2) {
-      throw new Error(`DialogStateManager.deleteValue: invalid path of '${pathExpression}'.`)
+      throw ExceptionHelper.generateException(
+        Error,
+        Errors.InvalidDeletePath,
+        undefined,
+        { path: pathExpression }
+      )
     }
 
     // Track change
@@ -251,7 +274,12 @@ export class DialogStateManager {
     // Get memory scope to update
     const scope = this.getMemoryScope(segments[0].toString())
     if (scope === undefined) {
-      throw new Error(`DialogStateManager.deleteValue: a scope of '${segments[0]}' wasn't found.`)
+      throw ExceptionHelper.generateException(
+        Error,
+        Errors.ScopeNotFoundForDelete,
+        undefined,
+        { scope: segments[0].toString() }
+      )
     }
 
     // Find value up to last key
@@ -422,8 +450,11 @@ export class DialogStateManager {
             } else if (isValidPathChar(c)) {
               segment += c
             } else {
-              throw new Error(
-                                `DialogStateManager.normalizePath: Invalid path detected - ${pathExpression}`
+              throw ExceptionHelper.generateException(
+                Error,
+                Errors.InvalidPathCharacters,
+                undefined,
+                { path: pathExpression }
               )
             }
             break
@@ -431,7 +462,12 @@ export class DialogStateManager {
       }
     }
     if (depth > 0) {
-      throw new Error(`DialogStateManager.normalizePath: Invalid path detected - ${pathExpression}`)
+      throw ExceptionHelper.generateException(
+        Error,
+        Errors.InvalidPathCharacters,
+        undefined,
+        { path: pathExpression }
+      )
     } else if (segment.length > 0) {
       output.push(segment)
     }

package/src/memory/scopes/agentStateMemoryScope.ts

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 import { AgentState } from '@microsoft/agents-hosting'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../../errorHelper'
 import { MemoryScope } from './memoryScope'
 import { DialogContext } from '../../dialogContext'
 
@@ -45,9 +47,17 @@ export class AgentStateMemoryScope extends MemoryScope {
   setMemory (dialogContext: DialogContext, _memory: object): void {
     const agentState = dialogContext.context.turnState.get(this.stateKey)
     if (!agentState) {
-      throw new Error(`${this.stateKey} is not available.`)
+      throw ExceptionHelper.generateException(
+        Error,
+        Errors.StateKeyNotAvailable,
+        undefined,
+        { stateKey: this.stateKey }
+      )
     }
-    throw new Error('You cannot replace the root AgentState object.')
+    throw ExceptionHelper.generateException(
+      Error,
+      Errors.CannotReplaceRootAgentState
+    )
   }
 
   /**

package/src/memory/scopes/dialogMemoryScope.ts

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 import { MemoryScope } from './memoryScope'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../../errorHelper'
 import { ScopePath } from '../scopePath'
 import { DialogContext } from '../../dialogContext'
 import { DialogContainer } from '../../dialogContainer'
@@ -47,7 +49,12 @@ export class DialogMemoryScope extends MemoryScope {
    */
   setMemory (dialogContext: DialogContext, memory: object): void {
     if (memory === undefined) {
-      throw new Error('DialogMemoryScope.setMemory: undefined memory object passed in.')
+      throw ExceptionHelper.generateException(
+        Error,
+        Errors.UndefinedMemoryObject,
+        undefined,
+        { scopeName: 'DialogMemoryScope' }
+      )
     }
 
     // If active dialog is a container dialog then "dialog" binds to it.
@@ -60,7 +67,10 @@ export class DialogMemoryScope extends MemoryScope {
 
     // If there's no active dialog then throw an error.
     if (!parent.activeDialog) {
-      throw new Error('DialogMemoryScope.setMemory: no active dialog found.')
+      throw ExceptionHelper.generateException(
+        Error,
+        Errors.ActiveDialogUndefined
+      )
     }
 
     parent.activeDialog.state = memory

package/src/memory/scopes/memoryScope.ts

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 import { DialogContext } from '../../dialogContext'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../../errorHelper'
 
 /**
  * Abstract base class for all memory scopes.
@@ -38,7 +40,12 @@ export abstract class MemoryScope {
      * @param _memory memory to assign
      */
   setMemory (_dialogContext: DialogContext, _memory: object): void {
-    throw new Error(`MemoryScope.setMemory: The '${this.name}' memory scope is read-only.`)
+    throw ExceptionHelper.generateException(
+      Error,
+      Errors.MemoryScopeOperationNotSupported,
+      undefined,
+      { scopeName: this.name, operation: 'setMemory' }
+    )
   }
 
   /**
@@ -65,6 +72,11 @@ export abstract class MemoryScope {
      * @param _dialogContext Current dialog context.
      */
   async delete (_dialogContext: DialogContext): Promise<void> {
-    throw new Error(`MemoryScope.delete: The '${this.name}' memory scope can't be deleted.`)
+    throw ExceptionHelper.generateException(
+      Error,
+      Errors.MemoryScopeOperationNotSupported,
+      undefined,
+      { scopeName: this.name, operation: 'delete' }
+    )
   }
 }

package/src/memory/scopes/thisMemoryScope.ts

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 import { MemoryScope } from './memoryScope'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../../errorHelper'
 import { ScopePath } from '../scopePath'
 import { DialogContext } from '../../dialogContext'
 
@@ -32,11 +34,19 @@ export class ThisMemoryScope extends MemoryScope {
      */
   setMemory (dialogContext: DialogContext, memory: object): void {
     if (memory === undefined) {
-      throw new Error('ThisMemoryScope.setMemory: undefined memory object passed in.')
+      throw ExceptionHelper.generateException(
+        Error,
+        Errors.UndefinedMemoryObject,
+        undefined,
+        { scopeName: 'ThisMemoryScope' }
+      )
     }
 
     if (!dialogContext.activeDialog) {
-      throw new Error('ThisMemoryScope.setMemory: no active dialog found.')
+      throw ExceptionHelper.generateException(
+        Error,
+        Errors.ActiveDialogUndefined
+      )
     }
 
     dialogContext.activeDialog.state = memory

package/src/memory/scopes/turnMemoryScope.ts

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 import { MemoryScope } from './memoryScope'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../../errorHelper'
 import { ScopePath } from '../scopePath'
 import { DialogContext } from '../../dialogContext'
 
@@ -47,7 +49,12 @@ export class TurnMemoryScope extends MemoryScope {
    */
   setMemory (dialogContext: DialogContext, memory: object): void {
     if (memory === undefined) {
-      throw new Error('TurnMemoryScope.setMemory: undefined memory object passed in.')
+      throw ExceptionHelper.generateException(
+        Error,
+        Errors.UndefinedMemoryObject,
+        undefined,
+        { scopeName: 'TurnMemoryScope' }
+      )
     }
 
     dialogContext.context.turnState.set(TURN_STATE, memory)

package/src/prompts/choicePrompt.ts

@@ -134,10 +134,11 @@ export class ChoicePrompt extends Prompt<FoundChoice> {
     const channelId = context.activity.channelId
     const choiceOptions = this.choiceOptions || this.choiceDefaults[locale]
     const choiceStyle: ListStyle = options.style === 0 ? 0 : options.style || this.style
+    const conversationType = context.activity.conversation?.conversationType
     if (isRetry && options.retryPrompt) {
-      prompt = this.appendChoices(options.retryPrompt, channelId, choices, choiceStyle, choiceOptions)
+      prompt = this.appendChoices(options.retryPrompt, channelId, choices, choiceStyle, choiceOptions, conversationType)
     } else {
-      prompt = this.appendChoices(options.prompt, channelId, choices, choiceStyle, choiceOptions)
+      prompt = this.appendChoices(options.prompt, channelId, choices, choiceStyle, choiceOptions, conversationType)
     }
 
     // Send prompt

package/src/prompts/confirmPrompt.ts

@@ -167,10 +167,11 @@ export class ConfirmPrompt extends Prompt<boolean> {
     const culture = this.determineCulture(context.activity)
     const choiceOptions = this.choiceOptions || this.choiceDefaults[culture].options
     const choices = this.confirmChoices || this.choiceDefaults[culture].choices
+    const conversationType = context.activity.conversation?.conversationType
     if (isRetry && options.retryPrompt) {
-      prompt = this.appendChoices(options.retryPrompt, channelId, choices, this.style, choiceOptions)
+      prompt = this.appendChoices(options.retryPrompt, channelId, choices, this.style, choiceOptions, conversationType)
     } else {
-      prompt = this.appendChoices(options.prompt, channelId, choices, this.style, choiceOptions)
+      prompt = this.appendChoices(options.prompt, channelId, choices, this.style, choiceOptions, conversationType)
     }
 
     // Send prompt

package/src/prompts/prompt.ts

@@ -401,6 +401,7 @@ export abstract class Prompt<T> extends Dialog {
      * @param choices List of choices to append.
      * @param style Configured style for the list of choices.
      * @param options (Optional) options to configure the underlying ChoiceFactory call.
+     * @param conversationType (Optional) the type of the conversation.
      * @returns The composed activity ready to send to the user.
      */
   protected appendChoices (
@@ -408,7 +409,8 @@ export abstract class Prompt<T> extends Dialog {
     channelId: string,
     choices: (string | Choice)[],
     style: ListStyle,
-    options?: ChoiceFactoryOptions
+    options?: ChoiceFactoryOptions,
+    conversationType?: string
   ): Activity {
     // Get base prompt text (if any)
     let text = ''
@@ -429,12 +431,20 @@ export abstract class Prompt<T> extends Dialog {
         msg = ChoiceFactory.list(choices, text, undefined, options)
         break
 
+      case ListStyle.suggestedAction:
+        msg = ChoiceFactory.suggestedActions(choices, text)
+        break
+
+      case ListStyle.heroCard:
+        msg = ChoiceFactory.heroCard(choices, text)
+        break
+
       case ListStyle.none:
         msg = MessageFactory.text(text)
         break
 
       default:
-        msg = ChoiceFactory.forChannel(channelId, choices, text, undefined, options)
+        msg = ChoiceFactory.forChannel(channelId, choices, text, undefined, options, conversationType)
         break
     }
 

package/src/recognizer.ts

@@ -2,7 +2,8 @@
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Licensed under the MIT License.
  */
-import { Activity } from '@microsoft/agents-activity'
+import { Activity, ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from './errorHelper'
 import { Configurable } from './configurable'
 import { DialogContext } from './dialogContext'
 import omit from 'lodash/omit'
@@ -58,7 +59,10 @@ export class Recognizer extends Configurable implements RecognizerConfiguration
     _telemetryProperties?: Record<string, string>,
     _telemetryMetrics?: Record<string, number>
   ): Promise<RecognizerResult> {
-    throw new Error('Please implement recognize function.')
+    throw ExceptionHelper.generateException(
+      Error,
+      Errors.RecognizeFunctionNotImplemented
+    )
   }
 
   /**

package/src/recognizerResult.ts

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 import { IntentScore } from './intentScore'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from './errorHelper'
 
 /**
  * Value returned from a recognizer.
@@ -64,7 +66,10 @@ export interface RecognizerResult {
  */
 export const getTopScoringIntent = (result: RecognizerResult): { intent: string; score: number } => {
   if (!result || !result.intents) {
-    throw new Error('result is empty')
+    throw ExceptionHelper.generateException(
+      Error,
+      Errors.EmptyRecognizerResult
+    )
   }
 
   let topIntent = ''

package/src/waterfallDialog.ts

@@ -3,7 +3,8 @@
  * Licensed under the MIT License.
  */
 import { v4 as uuidv4 } from 'uuid'
-import { ActivityTypes } from '@microsoft/agents-activity'
+import { ActivityTypes, ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from './errorHelper'
 import { Dialog } from './dialog'
 import { DialogContext } from './dialogContext'
 import { WaterfallStepContext } from './waterfallStepContext'
@@ -172,8 +173,11 @@ export class WaterfallDialog<O extends object = {}> extends Dialog<O> {
         values: state.values,
         onNext: async (stepResult?: any): Promise<DialogTurnResult<any>> => {
           if (nextCalled) {
-            throw new Error(
-                            `WaterfallStepContext.next(): method already called for dialog and step '${this.id}[${index}]'.`
+            throw ExceptionHelper.generateException(
+              Error,
+              Errors.WaterfallStepError,
+              undefined,
+              { stepIndex: index.toString() }
             )
           }
           nextCalled = true