@microsoft/agents-hosting-dialogs 1.0.0 → 1.0.7-g73d3d58001

package/src/dialogInstance.ts

@@ -11,22 +11,22 @@
  */
 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 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.
-       */
+   * 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.
-       */
+   * Hash code used to detect that a dialog has changed since the current instance was started.
+   */
   version?: string;
 }

package/src/dialogReason.ts

@@ -8,33 +8,33 @@
  */
 export enum DialogReason {
   /**
-       * The dialog is being started from DialogContext.beginDialog or DialogContext.replaceDialog.
-       */
+   * The dialog is being started from DialogContext.beginDialog or DialogContext.replaceDialog.
+   */
   beginCalled = 'beginCalled',
 
   /**
-       * The dialog is being continued from DialogContext.continueDialog.
-       */
+   * The dialog is being continued from DialogContext.continueDialog.
+   */
   continueCalled = 'continueCalled',
 
   /**
-       * The dialog is being ended from DialogContext.endDialog.
-       */
+   * The dialog is being ended from DialogContext.endDialog.
+   */
   endCalled = 'endCalled',
 
   /**
-       * The dialog is being ended from DialogContext.replaceDialog.
-       */
+   * The dialog is being ended from DialogContext.replaceDialog.
+   */
   replaceCalled = 'replaceCalled',
 
   /**
-       * The dialog is being cancelled from DialogContext.cancelAllDialogs.
-       */
+   * 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.
-       */
+   * 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

@@ -12,7 +12,7 @@ import { DialogContext, DialogState } from './dialogContext'
 import { StringUtils } from './stringUtils'
 
 /**
- * @summary Interface for dialogs that have child dialog dependencies.
+ * Interface for dialogs that have child dialog dependencies.
  *
  * @remarks
  * Implement this interface on dialog classes that need to register child dialogs
@@ -38,7 +38,7 @@ import { StringUtils } from './stringUtils'
  */
 export interface DialogDependencies {
   /**
-   * @summary Returns an array of child dialogs that this dialog depends on.
+   * Returns an array of child dialogs that this dialog depends on.
    *
    *
    * @remarks
@@ -64,7 +64,7 @@ export interface DialogDependencies {
  * persist the dialog stack for the set:
  *
  * To interact with the sets dialogs you can call `createcontext` with the
- * current {@link @microsoft/agents-hosting.TurnContext}. That will create a {@link DialogContext} that can be used to start or continue
+ * current {@link TurnContext}. That will create a {@link DialogContext} that can be used to start or continue
  * execution of the sets dialogs:
  *
  */
@@ -76,12 +76,13 @@ export class DialogSet {
   /**
      * Creates a new DialogSet instance.
      *
+     * @param dialogState (Optional) state property used to persist the sets dialog stack.
+     *
      * @remarks
      * If the `dialogState` parameter is not passed in, calls to `createContext`
      * will return an error.  You will need to create a {@link 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
@@ -91,8 +92,10 @@ export class DialogSet {
      * 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) {
@@ -112,14 +115,15 @@ export class DialogSet {
   /**
      * Adds a new dialog or prompt to the set.
      *
+     * @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.
+     *
      * @remarks
      * If the {@link 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)) {
@@ -184,6 +188,7 @@ export class DialogSet {
 
   /**
      * Finds a dialog that was previously added to the set using add.
+     *
      * @param dialogId ID of the dialog or prompt to lookup.
      * @returns The dialog if found; otherwise undefined.
      */

package/src/dialogTurnResult.ts

@@ -26,6 +26,7 @@ export interface DialogTurnResult<T = any> {
      * 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;
 

package/src/dialogTurnStateConstants.ts

@@ -9,6 +9,7 @@
  * @remarks
  * These constants are used as keys to store and retrieve specific state information
  * during the execution of a dialog turn.
+ *
  */
 export class DialogTurnStateConstants {
   /**

package/src/dialogTurnStatus.ts

@@ -9,6 +9,7 @@ export enum DialogTurnStatus {
      *
      * @remarks
      * Indicates that the dialog stack was initially empty when the operation was attempted.
+     *
      */
   empty = 'empty',
 

package/src/index.ts

@@ -34,3 +34,6 @@ export * from './configuration'
 export * from './intentScore'
 
 export { runDialog } from './dialogHelper'
+
+// Type-only re-export to avoid TypeDoc issues
+export type { TurnContext } from '@microsoft/agents-hosting'

package/src/memory/dialogPath.ts

@@ -9,49 +9,49 @@
 export class DialogPath {
   /**
    * Counter of emitted events.
-   * @constant A string key representing the event counter path (`'dialog.eventCounter'`).
+   * A string key representing the event counter path (`'dialog.eventCounter'`).
    */
   static readonly eventCounter: string = 'dialog.eventCounter'
 
   /**
    * Currently expected properties.
-   * @constant A string key representing the expected properties path (`'dialog.expectedProperties'`).
+   * A string key representing the expected properties path (`'dialog.expectedProperties'`).
    */
   static readonly expectedProperties: string = 'dialog.expectedProperties'
 
   /**
    * Default operation to use for entities where there is no identified operation entity.
-   * @constant A string key representing the default operation path (`'dialog.defaultOperation'`).
+   * A string key representing the default operation path (`'dialog.defaultOperation'`).
    */
   static readonly defaultOperation: string = 'dialog.defaultOperation'
 
   /**
    * Last surfaced entity ambiguity event.
-   * @constant A string key representing the last event path (`'dialog.lastEvent'`).
+   * A string key representing the last event path (`'dialog.lastEvent'`).
    */
   static readonly lastEvent: string = 'dialog.lastEvent'
 
   /**
    * Currently required properties.
-   * @constant A string key representing the required properties path (`'dialog.requiredProperties'`).
+   * A string key representing the required properties path (`'dialog.requiredProperties'`).
    */
   static readonly requiredProperties: string = 'dialog.requiredProperties'
 
   /**
    * Number of retries for the current Ask.
-   * @constant A string key representing the retries path (`'dialog.retries'`).
+   * A string key representing the retries path (`'dialog.retries'`).
    */
   static readonly retries: string = 'dialog.retries'
 
   /**
    * Last intent.
-   * @constant A string key representing the last intent path (`'dialog.lastIntent'`).
+   * A string key representing the last intent path (`'dialog.lastIntent'`).
    */
   static readonly lastIntent: string = 'dialog.lastIntent'
 
   /**
    * Last trigger event: defined in FormEvent, ask, clarifyEntity etc.
-   * @constant A string key representing the last trigger event path (`'dialog.lastTriggerEvent'`).
+   * A string key representing the last trigger event path (`'dialog.lastTriggerEvent'`).
    */
   static readonly lastTriggerEvent: string = 'dialog.lastTriggerEvent'
 }

package/src/memory/dialogStateManager.ts

@@ -129,12 +129,14 @@ export class DialogStateManager {
   /**
      * Get the value from memory using path expression.
      *
-     * @remarks
-     * This always returns a CLONE of the memory, any modifications to the result will not affect memory.
      * @typeParam T The value type to return.
      * @param pathExpression Path expression to use.
      * @param defaultValue (Optional) default value to use if the path isn't found. May be a function that returns the default value to use.
      * @returns The found value or undefined if not found and no `defaultValue` specified.
+     *
+     * @remarks
+     * This always returns a CLONE of the memory, any modifications to the result will not affect memory.
+     *
      */
   getValue<T = any>(pathExpression: string, defaultValue?: T | (() => T)): T {
     function returnDefault (): T {
@@ -274,6 +276,7 @@ export class DialogStateManager {
      *
      * @remarks
      * This should be called at the beginning of the turn.
+     *
      */
   async loadAllScopes (): Promise<void> {
     const scopes = this.configuration.memoryScopes
@@ -287,6 +290,7 @@ export class DialogStateManager {
      *
      * @remarks
      * This should be called at the end of the turn.
+     *
      */
   async saveAllChanges (): Promise<void> {
     const scopes = this.configuration.memoryScopes
@@ -315,11 +319,12 @@ export class DialogStateManager {
   /**
      * Normalizes the path segments of a passed in path.
      *
-     * @remarks
-     * A path of `profile.address[0]` will be normalized to `profile.address.0`.
      * @param pathExpression The path to normalize.
      * @param allowNestedPaths Optional. If `false` then detection of a nested path will cause an empty path to be returned. Defaults to 'true'.
      * @returns The normalized path.
+     *
+     * @remarks
+     * A path of `profile.address[0]` will be normalized to `profile.address.0`.
      */
   parsePath (pathExpression: string, allowNestedPaths = true): (string | number)[] {
     // Expand path segments

package/src/memory/turnPath.ts

@@ -9,73 +9,73 @@
 export class TurnPath {
   /**
    * The result from the last dialog that was called.
-   * @constant A string key representing the last result path (`'turn.lastresult'`).
+   * A string key representing the last result path (`'turn.lastresult'`).
    */
   static readonly lastResult: string = 'turn.lastresult'
 
   /**
    * The current activity for the turn.
-   * @constant A string key representing the activity path (`'turn.activity'`).
+   * A string key representing the activity path (`'turn.activity'`).
    */
   static readonly activity: string = 'turn.activity'
 
   /**
    * The recognized result for the current turn.
-   * @constant A string key representing the recognized result path (`'turn.recognized'`).
+   * A string key representing the recognized result path (`'turn.recognized'`).
    */
   static readonly recognized: string = 'turn.recognized'
 
   /**
    * Path to the top intent.
-   * @constant A string key representing the top intent path (`'turn.recognized.intent'`).
+   * A string key representing the top intent path (`'turn.recognized.intent'`).
    */
   static readonly topIntent: string = 'turn.recognized.intent'
 
   /**
    * Path to the top score.
-   * @constant A string key representing the top score path (`'turn.recognized.score'`).
+   * A string key representing the top score path (`'turn.recognized.score'`).
    */
   static readonly topScore: string = 'turn.recognized.score'
 
   /**
    * Original text.
-   * @constant A string key representing the original text path (`'turn.recognized.text'`).
+   * A string key representing the original text path (`'turn.recognized.text'`).
    */
   static readonly text: string = 'turn.recognized.text'
 
   /**
    * Original utterance split into unrecognized strings.
-   * @constant A string key representing the unrecognized text path (`'turn.unrecognizedText'`).
+   * A string key representing the unrecognized text path (`'turn.unrecognizedText'`).
    */
   static readonly unrecognizedText: string = 'turn.unrecognizedText'
 
   /**
    * Entities that were recognized from text.
-   * @constant A string key representing the recognized entities path (`'turn.recognizedEntities'`).
+   * A string key representing the recognized entities path (`'turn.recognizedEntities'`).
    */
   static readonly recognizedEntities: string = 'turn.recognizedEntities'
 
   /**
    * If true, an interruption has occurred.
-   * @constant A string key representing the interrupted path (`'turn.interrupted'`).
+   * A string key representing the interrupted path (`'turn.interrupted'`).
    */
   static readonly interrupted: string = 'turn.interrupted'
 
   /**
    * The current dialog event (set during event processing).
-   * @constant A string key representing the dialog event path (`'turn.dialogEvent'`).
+   * A string key representing the dialog event path (`'turn.dialogEvent'`).
    */
   static readonly dialogEvent: string = 'turn.dialogEvent'
 
   /**
    * Used to track that we don't end up in an infinite loop of RepeatDialogs().
-   * @constant A string key representing the repeated IDs path (`'turn.repeatedIds'`).
+   * A string key representing the repeated IDs path (`'turn.repeatedIds'`).
    */
   static readonly repeatedIds: string = 'turn.repeatedIds'
 
   /**
    * Indicates whether the turncontext.activity has been consumed by some component in the system.
-   * @constant A string key representing the activity processed path (`'turn.activityProcessed'`).
+   * A string key representing the activity processed path (`'turn.activityProcessed'`).
    */
   static readonly activityProcessed: string = 'turn.activityProcessed'
 }

package/src/prompts/activityPrompt.ts

@@ -41,9 +41,11 @@ export class ActivityPrompt extends Dialog {
      * @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
@@ -72,11 +74,13 @@ export class ActivityPrompt extends Dialog {
      * @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

package/src/prompts/attachmentPrompt.ts

@@ -11,6 +11,7 @@ import { Attachment, InputHints } from '@microsoft/agents-activity'
  *
  * @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

package/src/prompts/choicePrompt.ts

@@ -16,6 +16,7 @@ import { Activity } from '@microsoft/agents-activity'
  * @remarks
  * This interface is used to define the default options for rendering choices in prompts,
  * such as separators, inline options, and whether to include numbers.
+ *
  */
 export interface ChoiceDefaultsChoicePrompt {
   /**
@@ -24,6 +25,7 @@ export interface ChoiceDefaultsChoicePrompt {
    * @remarks
    * Each locale key maps to a `ChoiceFactoryOptions` object that defines the
    * default behavior for rendering choices in that locale.
+   *
    */
   [locale: string]: ChoiceFactoryOptions;
 }
@@ -34,6 +36,7 @@ export interface ChoiceDefaultsChoicePrompt {
  * @remarks
  * By default the prompt will return to the calling dialog a {@link FoundChoice} object containing the
  * choice that was selected.
+ *
  */
 export class ChoicePrompt extends Prompt<FoundChoice> {
   /**
@@ -52,6 +55,7 @@ export class ChoicePrompt extends Prompt<FoundChoice> {
      *
      * @remarks
      * Defaults to `ListStyle.auto`.
+     *
      */
   style: ListStyle
 

package/src/prompts/confirmPrompt.ts

@@ -10,7 +10,7 @@ import { PromptCultureModels } from './promptCultureModels'
 import { Activity } from '@microsoft/agents-activity'
 
 /**
- * @summary Defines locale-specific choice defaults for confirmation prompts.
+ * Defines locale-specific choice defaults for confirmation prompts.
  *
  * @remarks
  * This interface represents a dictionary that maps locale strings to their corresponding
@@ -50,6 +50,7 @@ export interface ChoiceDefaultsConfirmPrompt {
    * @remarks
    * The key is a locale string (e.g., 'en-us', 'fr-fr', 'de-de') and the value
    * contains the localized choices and formatting options for that locale.
+   *
    */
   [locale: string]: {
     /**
@@ -71,6 +72,7 @@ export interface ChoiceDefaultsConfirmPrompt {
  * @remarks
  * By default the prompt will return to the calling dialog a `boolean` representing the users
  * selection.
+ *
  */
 export class ConfirmPrompt extends Prompt<boolean> {
   /**
@@ -89,6 +91,7 @@ export class ConfirmPrompt extends Prompt<boolean> {
      *
      * @remarks
      * Defaults to {@link ListStyle.auto}.
+     *
      */
   style: ListStyle
 

package/src/prompts/datetimePrompt.ts

@@ -34,6 +34,7 @@ export interface DateTimeResolution {
  *
  * @remarks
  * By default the prompt will return to the calling dialog a {@link DateTimeResolution | DateTimeResolution[] }.
+ *
  */
 export class DateTimePrompt extends Prompt<DateTimeResolution[]> {
   /**

package/src/prompts/numberPrompt.ts

@@ -18,6 +18,7 @@ Object.values(locales).forEach((locale) => Globalize.load(locale))
  *
  * @remarks
  * By default the prompt will return to the calling dialog a `number` representing the users input.
+ *
  */
 export class NumberPrompt extends Prompt<number> {
   /**

package/src/prompts/prompt.ts

@@ -103,7 +103,10 @@ export interface PromptRecognizerResult<T> {
 }
 
 /**
- * @summary Function signature for providing a custom prompt validator.
+ * Function signature for providing a custom prompt validator.
+ *
+ * @param T Type of recognizer result being validated.
+ * @param prompt Contextual information containing the recognizer result and original options passed to the prompt.
  *
  * @remarks
  * The validator should be an asynchronous function that returns `true` if
@@ -118,8 +121,7 @@ export interface PromptRecognizerResult<T> {
  * ```typescript
  * type PromptValidator<T> = (prompt: PromptValidatorContext<T>) => Promise<boolean>;
  * ```
- * @param T Type of recognizer result being validated.
- * @param prompt Contextual information containing the recognizer result and original options passed to the prompt.
+ *
  */
 export type PromptValidator<T> = (prompt: PromptValidatorContext<T>) => Promise<boolean>
 
@@ -134,6 +136,7 @@ export interface PromptValidatorContext<T> {
      *
      * @remarks
      * The validator can use this to re-prompt the user.
+     *
      */
   readonly context: TurnContext;
 
@@ -141,8 +144,9 @@ export interface PromptValidatorContext<T> {
      * Result returned from the prompts recognizer function.
      *
      * @remarks
-     * The {@link @microsoft/agents-hosting-dialogs.PromptRecognizerResult.succeeded | recognized.succeeded} field can be checked to determine of the recognizer found
-     * anything and then the value can be retrieved from {@link @microsoft/agents-hosting-dialogs.PromptRecognizerResult.value | recognized.value}.
+     * The {@link PromptRecognizerResult.succeeded | recognized.succeeded} field can be checked to determine of the recognizer found
+     * anything and then the value can be retrieved from {@link PromptRecognizerResult.value | recognized.value}.
+     *
      */
   readonly recognized: PromptRecognizerResult<T>;
 
@@ -151,6 +155,7 @@ export interface PromptValidatorContext<T> {
      *
      * @remarks
      * The validator can use this to persist things like turn counts or other state information.
+     *
      */
   readonly state: object;
 
@@ -159,6 +164,7 @@ export interface PromptValidatorContext<T> {
      *
      * @remarks
      * The validator can extend this interface to support additional prompt options.
+     *
      */
   readonly options: PromptOptions;
 
@@ -166,6 +172,7 @@ export interface PromptValidatorContext<T> {
      * A count of the number of times the prompt has been executed.
      *
      * A number indicating how many times the prompt was invoked (starting at 1 for the first time it was invoked).
+     *
      */
   readonly attemptCount: number;
 }
@@ -197,9 +204,11 @@ export abstract class Prompt<T> extends Dialog {
      * @param options Optional. PromptOptions,
      * additional information to pass to the prompt being started.
      * @returns A `Promise` representing the asynchronous operation.
+     *
      * @remarks
      * If the task 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
@@ -227,11 +236,13 @@ export abstract class Prompt<T> extends Dialog {
      *
      * @param dialogContext The DialogContext for the current turn of conversation.
      * @returns A `Promise` representing the asynchronous operation.
+     *
      * @remarks
      * If the task 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> {
     // Don't do anything for non-message activities
@@ -288,10 +299,12 @@ export abstract class Prompt<T> extends Dialog {
      * @param dialogContext The DialogContext for the current turn of conversation.
      * @param event DialogEvent, the event being raised.
      * @returns Whether the event is handled by the current dialog and further processing should stop.
+     *
      * @remarks
      * This is a good place to perform interception of an event as returning `true` will prevent
      * any further bubbling of the event to the dialogs parents and will also prevent any child
      * dialogs from performing their default processing.
+     *
      */
   protected async onPreBubbleEvent (dialogContext: DialogContext, event: DialogEvent): Promise<boolean> {
     if (event.name === 'activityReceived' && dialogContext.context.activity.type === ActivityTypes.Message) {
@@ -317,9 +330,11 @@ export abstract class Prompt<T> extends Dialog {
      * @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.
+     *
      * @remarks
      * If the task is successful, the result indicates whether the dialog is still
      * active after the turn has been processed by the dialog.
+     *
      */
   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
@@ -364,12 +379,13 @@ export abstract class Prompt<T> extends Dialog {
   /**
      * Called to recognize an utterance received from the user.
      *
-     * @remarks
-     * The Prompt class filters out non-message activities so its safe to assume that the users
-     * utterance can be retrieved from `context.activity.text`.
      * @param context Context for the current turn of conversation with the user.
      * @param state Additional state being persisted for the prompt.
      * @param options Options that the prompt was started with in the call to `DialogContext.prompt()`.
+     *
+     * @remarks
+     * The Prompt class filters out non-message activities so its safe to assume that the users
+     * utterance can be retrieved from `context.activity.text`.
      */
   protected abstract onRecognize (
     context: TurnContext,