@microsoft/agents-hosting-dialogs 0.1.49

package/dist/src/waterfallStepContext.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { DialogContext } from './dialogContext';
+import { DialogReason } from './dialogReason';
+import { DialogTurnResult } from './dialogTurnResult';
+/**
+ * Values passed to the `WaterfallStepContext` constructor.
+ */
+export interface WaterfallStepInfo<O extends object> {
+    index: number;
+    options: O;
+    reason: DialogReason;
+    result: any;
+    values: object;
+    onNext(result?: any): Promise<DialogTurnResult>;
+}
+/**
+ * Context object passed in to a `WaterfallStep`.
+ *
+ * @param O (Optional) type of options passed to the steps waterfall dialog in the call to `DialogContext.beginDialog()`.
+ */
+export declare class WaterfallStepContext<O extends object = {}> extends DialogContext {
+    private _stepInfo;
+    /**
+       * Creates a new WaterfallStepContext instance.
+       *
+       * @param dialogContext The dialog context for the current turn of conversation.
+       * @param stepInfo Values to initialize the step context with.
+       */
+    constructor(dialogContext: DialogContext, stepInfo: WaterfallStepInfo<O>);
+    /**
+       * The index of the current waterfall step being executed.
+       *
+       * @returns The index of the current waterfall step being executed.
+       */
+    get index(): number;
+    /**
+       * Any options passed to the steps waterfall dialog when it was started with
+       * `DialogContext.beginDialog()`.
+       *
+       * @returns Any options the waterfall dialog was called with.
+       */
+    get options(): O;
+    /**
+       * The reason the waterfall step is being executed.
+       *
+       * @returns The reason the waterfall step is being executed.
+       */
+    get reason(): DialogReason;
+    /**
+       * Results returned by a dialog or prompt that was called in the previous waterfall step.
+       *
+       * @returns The result from the previous waterfall step.
+       */
+    get result(): any;
+    /**
+       * A dictionary of values which will be persisted across all waterfall steps.
+       *
+       * @returns A dictionary of values which will be persisted across all waterfall steps.
+       */
+    get values(): object;
+    /**
+       * Skips to the next waterfall step.
+       *
+       * @param result (Optional) result to pass to the next step.
+       * @returns A promise with the DialogTurnResult.
+       */
+    next(result?: any): Promise<DialogTurnResult>;
+}

package/dist/src/waterfallStepContext.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WaterfallStepContext = void 0;
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+const dialogContext_1 = require("./dialogContext");
+/**
+ * Context object passed in to a `WaterfallStep`.
+ *
+ * @param O (Optional) type of options passed to the steps waterfall dialog in the call to `DialogContext.beginDialog()`.
+ */
+class WaterfallStepContext extends dialogContext_1.DialogContext {
+    /**
+       * Creates a new WaterfallStepContext instance.
+       *
+       * @param dialogContext The dialog context for the current turn of conversation.
+       * @param stepInfo Values to initialize the step context with.
+       */
+    constructor(dialogContext, stepInfo) {
+        super(dialogContext.dialogs, dialogContext, { dialogStack: dialogContext.stack });
+        this._stepInfo = stepInfo;
+        this.parent = dialogContext.parent;
+    }
+    /**
+       * The index of the current waterfall step being executed.
+       *
+       * @returns The index of the current waterfall step being executed.
+       */
+    get index() {
+        return this._stepInfo.index;
+    }
+    /**
+       * Any options passed to the steps waterfall dialog when it was started with
+       * `DialogContext.beginDialog()`.
+       *
+       * @returns Any options the waterfall dialog was called with.
+       */
+    get options() {
+        return this._stepInfo.options;
+    }
+    /**
+       * The reason the waterfall step is being executed.
+       *
+       * @returns The reason the waterfall step is being executed.
+       */
+    get reason() {
+        return this._stepInfo.reason;
+    }
+    /**
+       * Results returned by a dialog or prompt that was called in the previous waterfall step.
+       *
+       * @returns The result from the previous waterfall step.
+       */
+    get result() {
+        return this._stepInfo.result;
+    }
+    /**
+       * A dictionary of values which will be persisted across all waterfall steps.
+       *
+       * @returns A dictionary of values which will be persisted across all waterfall steps.
+       */
+    get values() {
+        return this._stepInfo.values;
+    }
+    /**
+       * Skips to the next waterfall step.
+       *
+       * @param result (Optional) result to pass to the next step.
+       * @returns A promise with the DialogTurnResult.
+       */
+    async next(result) {
+        return await this._stepInfo.onNext(result);
+    }
+}
+exports.WaterfallStepContext = WaterfallStepContext;
+//# sourceMappingURL=waterfallStepContext.js.map

package/dist/src/waterfallStepContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"waterfallStepContext.js","sourceRoot":"","sources":["../../src/waterfallStepContext.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,mDAA+C;AAgB/C;;;;GAIG;AACH,MAAa,oBAA4C,SAAQ,6BAAa;IAG5E;;;;;SAKK;IACL,YAAa,aAA4B,EAAE,QAA8B;QACvE,KAAK,CAAC,aAAa,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,WAAW,EAAE,aAAa,CAAC,KAAK,EAAE,CAAC,CAAA;QACjF,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;QACzB,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,MAAM,CAAA;IACpC,CAAC;IAED;;;;SAIK;IACL,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAA;IAC7B,CAAC;IAED;;;;;SAKK;IACL,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAA;IAC/B,CAAC;IAED;;;;SAIK;IACL,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAA;IAC9B,CAAC;IAED;;;;SAIK;IACL,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAA;IAC9B,CAAC;IAED;;;;SAIK;IACL,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAA;IAC9B,CAAC;IAED;;;;;SAKK;IACL,KAAK,CAAC,IAAI,CAAE,MAAY;QACtB,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC5C,CAAC;CACF;AAtED,oDAsEC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@microsoft/agents-hosting-dialogs",
+  "version": "0.1.49",
+  "homepage": "https://github.com/microsoft/Agents-for-js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microsoft/Agents-for-js.git"
+  },
+  "author": {
+    "name": "Microsoft",
+    "email": "agentssdk@microsoft.com",
+    "url": "https://aka.ms/Agents"
+  },
+  "description": "Microsoft 365 Agents SDK Dialogs support.",
+  "main": "dist/index.js",
+  "types": "dist/src/index.d.ts",
+  "dependencies": {
+    "@microsoft/agents-hosting": "0.1.49",
+    "@types/lodash": "^4.17.16",
+    "dependency-graph": "^1.0.0",
+    "@microsoft/recognizers-text-suite": "^1.3.1",
+    "@microsoft/recognizers-text-number": "^1.3.1",
+    "@microsoft/recognizers-text-date-time": "^1.3.2",
+    "@microsoft/recognizers-text-choice": "^1.3.1",
+    "globalize": "^1.7.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.1"
+  },
+  "license": "MIT",
+  "files": [
+    "README.md",
+    "dist/src",
+    "dist/vendor",
+    "src",
+    "vendor"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "require": "./dist/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/agentComponent.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import * as z from 'zod'
+import { ServiceCollection } from './serviceCollection'
+import { Configuration } from './configuration'
+
+/**
+ * Definition of an AgentComponent that allows registration of services, custom actions, memory scopes and adapters.
+ *
+ * To make your components available to the system you derive from AgentComponent and register services to add functionality.
+ * These components then are consumed in appropriate places by the systems that need them. When using Composer, configureServices
+ * gets called automatically on the components by the agent runtime, as long as the components are registered in the configuration.
+ */
+export abstract class AgentComponent {
+  static z = z.custom<AgentComponent>((val: any) => typeof val.configureServices === 'function', {
+    message: 'AgentComponent',
+  })
+
+  abstract configureServices (services: ServiceCollection, configuration: Configuration): void
+}

package/src/agentStateSet.ts

@@ -0,0 +1,75 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { AgentState, TurnContext } from '@microsoft/agents-hosting'
+
+/**
+ * A collection of `AgentState` plugins that should be loaded or saved in parallel as a single unit.
+ * See `AutoSaveStateMiddleware` for an implementation of this class.
+ */
+export class AgentStateSet {
+  /**
+     * Array of the sets `AgentState` plugins.
+     */
+  readonly agentStates: AgentState[] = []
+
+  /**
+     * Creates a new AgentStateSet instance.
+     *
+     * @param agentStates One or more AgentState plugins to register.
+     */
+  constructor (...agentStates: AgentState[]) {
+    AgentStateSet.prototype.add.apply(this, agentStates)
+  }
+
+  /**
+     * Registers one or more `AgentState` plugins with the set.
+     *
+     * @param agentStates One or more AgentState plugins to register.
+     * @returns The updated AgentStateSet.
+     */
+  add (...agentStates: AgentState[]): this {
+    agentStates.forEach((agentstate: AgentState) => {
+      if (typeof agentstate.load === 'function' && typeof agentstate.saveChanges === 'function') {
+        this.agentStates.push(agentstate)
+      } else {
+        throw new Error("AgentStateSet: a object was added that isn't an instance of AgentStateSet.")
+      }
+    })
+
+    return this
+  }
+
+  /**
+     * Calls `AgentState.load()` on all of the AgentState plugins in the set.
+     *
+     * @remarks
+     * This will trigger all of the plugins to read in their state in parallel.
+     *
+     * @param context Context for current turn of conversation with the user.
+     * @param force (Optional) If `true` the cache will be bypassed and the state will always be read in directly from storage. Defaults to `false`.
+     */
+  async loadAll (context: TurnContext, force = false): Promise<void> {
+    const promises: Promise<any>[] = this.agentStates.map((agentstate: AgentState) => agentstate.load(context, force))
+
+    await Promise.all(promises)
+  }
+
+  /**
+     * Calls `AgentState.saveChanges()` on all of the AgentState plugins in the set.
+     *
+     * @remarks
+     * This will trigger all of the plugins to write out their state in parallel.
+     *
+     * @param context Context for current turn of conversation with the user.
+     * @param force (Optional) if `true` the state will always be written out regardless of its change state. Defaults to `false`.
+     */
+  async saveAllChanges (context: TurnContext, force = false): Promise<void> {
+    const promises: Promise<void>[] = this.agentStates.map((agentstate: AgentState) =>
+      agentstate.saveChanges(context, force)
+    )
+
+    await Promise.all(promises)
+  }
+}

package/src/choices/choice.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { CardAction } from '@microsoft/agents-hosting'
+
+/**
+ * An instance of a choice that can be used to render a choice to a user or recognize something a
+ * user picked.
+ */
+export interface Choice {
+  value: string;
+  action?: CardAction;
+  synonyms?: string[];
+}

package/src/choices/choiceFactory.ts

@@ -0,0 +1,189 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+  ActionTypes,
+  Activity,
+  InputHints,
+  MessageFactory,
+  TurnContext,
+} from '@microsoft/agents-hosting'
+import { Choice } from './choice'
+
+/**
+ * Additional options used to tweak the formatting of choice lists.
+ */
+export interface ChoiceFactoryOptions {
+  /**
+     * (Optional) character used to separate individual choices when there are more than 2 choices.
+     * The default value is `", "`.
+     */
+  inlineSeparator?: string;
+
+  /**
+     * (Optional) separator inserted between the choices when their are only 2 choices. The default
+     * value is `" or "`.
+     */
+  inlineOr?: string;
+
+  /**
+     * (Optional) separator inserted between the last 2 choices when their are more than 2 choices.
+     * The default value is `", or "`.
+     */
+  inlineOrMore?: string;
+
+  /**
+     * (Optional) if `true`, inline and list style choices will be prefixed with the index of the
+     * choice as in "1. choice". If `false`, the list style will use a bulleted list instead. The
+     * default value is `true`.
+     */
+  includeNumbers?: boolean;
+}
+
+/**
+ * A set of utility functions to assist with the formatting a 'message' activity containing a list
+ * of choices.
+ *
+ */
+export class ChoiceFactory {
+  static readonly MAX_ACTION_TITLE_LENGTH = 20
+
+  /**
+     * Returns a 'message' activity containing a list of choices that has been automatically
+     * formatted based on the capabilities of a given channel.
+     *
+     * @param channelOrContext Channel ID or context object for the current turn of conversation.
+     * @param choices List of choices to render.
+     * @param text (Optional) text of the message.
+     * @param speak (Optional) SSML to speak for the message.
+     * @param options (Optional) formatting options to use when rendering as a list.
+     * @returns The created message activity.
+     */
+  static forChannel (
+    channelOrContext: string | TurnContext,
+    choices: (string | Choice)[],
+    text?: string,
+    speak?: string,
+    options?: ChoiceFactoryOptions
+  ): Activity {
+    const list: Choice[] = ChoiceFactory.toChoices(choices)
+
+    let maxTitleLength = 0
+    list.forEach((choice: Choice) => {
+      const l: number = choice.action && choice.action.title ? choice.action.title.length : choice.value.length
+      if (l > maxTitleLength) {
+        maxTitleLength = l
+      }
+    })
+
+    const longTitles: boolean = maxTitleLength > this.MAX_ACTION_TITLE_LENGTH
+    if (!longTitles && choices.length <= 3) {
+      // If the titles are short and there are 3 or less choices we'll use an inline list.
+      return ChoiceFactory.inline(list, text, speak, options)
+    } else {
+      return ChoiceFactory.list(list, text, speak, options)
+    }
+  }
+
+  /**
+     * Returns a 'message' activity containing a list of choices that has been formatted as an
+     * inline list.
+     *
+     * @param choices List of choices to render.
+     * @param text (Optional) text of the message.
+     * @param speak (Optional) SSML to speak for the message.
+     * @param options (Optional) formatting options to tweak rendering of list.
+     * @returns The created message activity.
+     */
+  static inline (
+    choices: (string | Choice)[],
+    text?: string,
+    speak?: string,
+    options?: ChoiceFactoryOptions
+  ): Activity {
+    const opt: ChoiceFactoryOptions = {
+      inlineSeparator: ', ',
+      inlineOr: ' or ',
+      inlineOrMore: ', or ',
+      includeNumbers: true,
+      ...options,
+    } as ChoiceFactoryOptions
+
+    let connector = ''
+    let txt: string = text || ''
+    txt += ' '
+    ChoiceFactory.toChoices(choices).forEach((choice: any, index: number) => {
+      const title: string = choice.action && choice.action.title ? choice.action.title : choice.value
+      txt += `${connector}${opt.includeNumbers ? '(' + (index + 1).toString() + ') ' : ''}${title}`
+      if (index === choices.length - 2) {
+        connector = (index === 0 ? opt.inlineOr : opt.inlineOrMore) || ''
+      } else {
+        connector = opt.inlineSeparator || ''
+      }
+    })
+    txt += ''
+
+    return MessageFactory.text(txt, speak, InputHints.ExpectingInput)
+  }
+
+  /**
+     * Returns a 'message' activity containing a list of choices that has been formatted as an
+     * numbered or bulleted list.
+     *
+     * @param choices List of choices to render.
+     * @param text (Optional) text of the message.
+     * @param speak (Optional) SSML to speak for the message.
+     * @param options (Optional) formatting options to tweak rendering of list.
+     * @returns The created message activity.
+     */
+  static list (
+    choices: (string | Choice)[],
+    text?: string,
+    speak?: string,
+    options?: ChoiceFactoryOptions
+  ): Activity {
+    const opt: ChoiceFactoryOptions = {
+      includeNumbers: true,
+      ...options,
+    } as ChoiceFactoryOptions
+
+    let connector = ''
+    let txt: string = text || ''
+    txt += '\n\n   '
+    ChoiceFactory.toChoices(choices).forEach((choice: any, index: number) => {
+      const title: string = choice.action && choice.action.title ? choice.action.title : choice.value
+      txt += `${connector}${opt.includeNumbers ? (index + 1).toString() + '. ' : '- '}${title}`
+      connector = '\n   '
+    })
+
+    return MessageFactory.text(txt, speak, InputHints.ExpectingInput)
+  }
+
+  /**
+     * Takes a mixed list of `string` and `Choice` based choices and returns them as a `Choice[]`.
+     *
+     * @param choices List of choices to add.
+     * @returns A list of choices.
+     */
+  static toChoices (choices: (string | Choice)[] | undefined): Choice[] {
+    return (choices || [])
+      .map((choice) => (typeof choice === 'string' ? { value: choice } : choice))
+      .map((choice: Choice) => {
+        const action = choice.action
+        if (action) {
+          action.type = action.type ? action.type : ActionTypes.ImBack
+          if (!action.value && action.title) {
+            action.value = action.title
+          } else if (!action.title && action.value) {
+            action.title = action.value
+          } else if (!action.title && !action.value) {
+            action.title = action.value = choice.value
+          }
+        }
+        return choice
+      })
+      .filter((choice: Choice) => choice)
+  }
+}

package/src/choices/findChoices.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { findValues, FindValuesOptions, FoundValue, SortedValue } from './findValues'
+import { ModelResult } from './modelResult'
+import { Choice } from './choice'
+
+export interface FindChoicesOptions extends FindValuesOptions {
+  noValue?: boolean;
+  noAction?: boolean;
+  recognizeNumbers?: boolean;
+  recognizeOrdinals?: boolean;
+}
+
+export interface FoundChoice {
+  value: string;
+  index: number;
+  score: number;
+  synonym?: string;
+}
+
+/**
+ * Mid-level search function for recognizing a choice in an utterance.
+ *
+ * @param utterance The text or user utterance to search over. For an incoming 'message' activity you can simply use `context.activity.text`.
+ * @param choices List of choices to search over.
+ * @param options (Optional) options used to tweak the search that's performed.
+ * @returns A list of found choices, sorted by most relevant first.
+ */
+export function findChoices (
+  utterance: string,
+  choices: (string | Choice)[],
+  options?: FindChoicesOptions
+): ModelResult<FoundChoice>[] {
+  const opt: FindChoicesOptions = options || {}
+
+  const list: Choice[] = (choices || []).map((choice) =>
+    typeof choice === 'string' ? { value: choice } : choice
+  )
+
+  const synonyms: SortedValue[] = []
+  list.forEach((choice: Choice, index: number) => {
+    if (!opt.noValue) {
+      synonyms.push({ value: choice.value, index })
+    }
+    if (choice.action && choice.action.title && !opt.noAction) {
+      synonyms.push({ value: choice.action.title, index })
+    }
+    (choice.synonyms || []).forEach((synonym: string) => synonyms.push({ value: synonym, index }))
+  })
+
+  return findValues(utterance, synonyms, options).map((v: ModelResult<FoundValue>) => {
+    const choice: Choice = list[v.resolution.index]
+
+    return {
+      start: v.start,
+      end: v.end,
+      typeName: 'choice',
+      text: v.text,
+      resolution: {
+        value: choice.value,
+        index: v.resolution.index,
+        score: v.resolution.score,
+        synonym: v.resolution.value,
+      },
+    } as ModelResult<FoundChoice>
+  })
+}