@microsoft/agents-hosting-dialogs 0.1.49

package/src/memory/pathResolvers/aliasPathResolver.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { PathResolver } from './pathResolver'
+
+export class AliasPathResolver implements PathResolver {
+  private readonly alias: string
+  private readonly prefix: string
+  private readonly postfix: string
+
+  /**
+     * Initializes a new instance of the AliasPathResolver class.
+     *
+     * @param alias Alias name.
+     * @param prefix Prefix name.
+     * @param postfix Postfix name.
+     */
+  constructor (alias: string, prefix: string, postfix?: string) {
+    this.alias = alias.trim()
+    this.prefix = prefix.trim()
+    this.postfix = postfix ? postfix.trim() : ''
+  }
+
+  /**
+     * Transforms the path.
+     *
+     * @param path Path to inspect.
+     * @returns The transformed path.
+     */
+  transformPath (path: string): string {
+    const start = path.indexOf(this.alias)
+    if (start === 0) {
+      // here we only deals with trailing alias, alias in middle be handled in further breakdown
+      // $xxx -> path.xxx
+      path = `${this.prefix}${path.substr(start + this.alias.length)}${this.postfix}`
+      if (path.endsWith('.')) {
+        path = path.substr(0, path.length - 1)
+      }
+    }
+
+    return path
+  }
+}

package/src/memory/pathResolvers/atAtPathResolver.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { AliasPathResolver } from './aliasPathResolver'
+
+export class AtAtPathResolver extends AliasPathResolver {
+  /**
+     * Initializes a new instance of the AtAtPathResolver class.
+     */
+  constructor () {
+    super('@@', 'turn.recognized.entities.')
+  }
+}

package/src/memory/pathResolvers/atPathResolver.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { AliasPathResolver } from './aliasPathResolver'
+
+export class AtPathResolver extends AliasPathResolver {
+  private readonly _prefix = 'turn.recognized.entities.'
+  private readonly _delims = ['.', '[']
+
+  /**
+     * Initializes a new instance of the AtPathResolver class.
+     */
+  constructor () {
+    super('@', '')
+  }
+
+  /**
+     * Transforms the path.
+     *
+     * @param path Path to inspect.
+     * @returns The transformed path.
+     */
+  transformPath (path: string): string {
+    path = path.trim()
+    if (path.startsWith('@') && path.length > 1 && !path.startsWith('@@')) {
+      let end = -1
+      for (let i = 0; i < this._delims.length; i++) {
+        const indexOfDelim = path.indexOf(this._delims[i])
+        if (indexOfDelim >= 0) {
+          end = indexOfDelim
+          break
+        }
+      }
+      if (end === -1) {
+        end = path.length
+      }
+      const property = path.substr(1, end - 1)
+      const suffix = path.substr(end)
+      path = `${this._prefix}${property}.first()${suffix}`
+    }
+
+    return path
+  }
+}

package/src/memory/pathResolvers/dollarPathResolver.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { AliasPathResolver } from './aliasPathResolver'
+
+export class DollarPathResolver extends AliasPathResolver {
+  /**
+     * Initializes a new instance of the DollarPathResolver class.
+     */
+  constructor () {
+    super('$', 'dialog.')
+  }
+}

package/src/memory/pathResolvers/hashPathResolver.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { AliasPathResolver } from './aliasPathResolver'
+
+export class HashPathResolver extends AliasPathResolver {
+  /**
+     * Initializes a new instance of the HashPathResolver class.
+     */
+  constructor () {
+    super('#', 'turn.recognized.intents.')
+  }
+}

package/src/memory/pathResolvers/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export * from './aliasPathResolver'
+export * from './atAtPathResolver'
+export * from './atPathResolver'
+export * from './dollarPathResolver'
+export * from './hashPathResolver'
+export * from './pathResolver'
+export * from './percentPathResolver'

package/src/memory/pathResolvers/pathResolver.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export interface PathResolver {
+  /**
+     * Transform the path
+     *
+     * @param path Path to inspect.
+     * @returns Transformed path
+     */
+  transformPath(path: string): string;
+}

package/src/memory/pathResolvers/percentPathResolver.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { AliasPathResolver } from './aliasPathResolver'
+
+export class PercentPathResolver extends AliasPathResolver {
+  /**
+     * Initializes a new instance of the PercentPathResolver class.
+     */
+  constructor () {
+    super('%', 'class.')
+  }
+}

package/src/memory/scopePath.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Defines paths for the available scopes.
+ */
+export class ScopePath {
+  static readonly user = 'user'
+  static readonly conversation = 'conversation'
+  static readonly dialog = 'dialog'
+  static readonly dialogClass = 'dialogClass'
+  static readonly dialogContext = 'dialogContext'
+  static readonly this = 'this'
+  static readonly class = 'class'
+  static readonly settings = 'settings'
+  static readonly turn = 'turn'
+}

package/src/memory/scopes/agentStateMemoryScope.ts

@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { AgentState } from '@microsoft/agents-hosting'
+import { MemoryScope } from './memoryScope'
+import { DialogContext } from '../../dialogContext'
+
+/**
+ * Base class for memory scopes based on AgentState.
+ */
+export class AgentStateMemoryScope extends MemoryScope {
+  protected stateKey: string
+
+  /**
+     * Initializes a new instance of the AgentStateMemoryScope class.
+     *
+     * @param name name of the property.
+     */
+  constructor (name: string) {
+    super(name, true)
+  }
+
+  /**
+     * Get the backing memory for this scope.
+     *
+     * @param dialogContext current dialog context.
+     * @returns Memory for the scope.
+     */
+  getMemory (dialogContext: DialogContext): object {
+    const agentState: AgentState = dialogContext.context.turnState.get(this.stateKey)
+    if (agentState) {
+      return agentState.get(dialogContext.context)
+    }
+
+    return undefined
+  }
+
+  /**
+     * Changes the backing object for the memory scope.
+     *
+     * @param dialogContext current dialog context
+     * @param _memory memory
+     */
+  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 new Error('You cannot replace the root AgentState object.')
+  }
+
+  /**
+     * Populates the state cache for this AgentState from the storage layer.
+     *
+     * @param dialogContext The DialogContext object for this turn.
+     * @param force Optional, `true` to overwrite any existing state cache;
+     * or `false` to load state from storage only if the cache doesn't already exist.
+     * @returns A Promise that represents the work queued to execute.
+     */
+  async load (dialogContext: DialogContext, force = false): Promise<void> {
+    const agentState: AgentState = dialogContext.context.turnState.get(this.stateKey)
+    if (agentState) {
+      await agentState.load(dialogContext.context, force)
+    }
+  }
+
+  /**
+     * Writes the state cache for this AgentState to the storage layer.
+     *
+     * @param dialogContext The DialogContext object for this turn.
+     * @param force Optional, `true` to save the state cache to storage;
+     * or `false` to save state to storage only if a property in the cache has changed.
+     * @returns A Promise that represents the work queued to execute.
+     */
+  async saveChanges (dialogContext: DialogContext, force = false): Promise<void> {
+    const agentState: AgentState = dialogContext.context.turnState.get(this.stateKey)
+    if (agentState) {
+      await agentState.saveChanges(dialogContext.context, force)
+    }
+  }
+
+  /**
+     * Deletes any state in storage and the cache for this AgentState.
+     *
+     * @param _dialogContext The DialogContext object for this turn.
+     * @returns A Promise that represents the work queued to execute.
+     */
+  async delete (_dialogContext: DialogContext): Promise<void> {
+    return Promise.resolve()
+  }
+}

package/src/memory/scopes/classMemoryScope.ts

@@ -0,0 +1,71 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { MemoryScope } from './memoryScope'
+import { ScopePath } from '../scopePath'
+import { DialogContext } from '../../dialogContext'
+import { Dialog } from '../../dialog'
+
+export class ClassMemoryScope extends MemoryScope {
+  /**
+     * Initializes a new instance of the ClassMemoryScope class.
+     *
+     * @param name Name of the scope class.
+     */
+  constructor (name = ScopePath.class) {
+    super(name, false)
+  }
+
+  /**
+     * Gets the backing memory for this scope.
+     *
+     * @param dialogContext The DialogContext object for this turn.
+     * @returns The memory for the scope.
+     */
+  getMemory (dialogContext: DialogContext): object {
+    // if active dialog is a container dialog then "dialog" binds to it
+    if (dialogContext.activeDialog) {
+      const dialog = this.onFindDialog(dialogContext)
+      if (dialog !== undefined) {
+        // Clone properties
+        const clone: object = {}
+        for (const key in dialog) {
+          const prop = dialog[key]
+          if (Object.prototype.hasOwnProperty.call(dialog, key) && typeof prop !== 'function') {
+            if (isExpression(prop)) {
+              const { value, error } = prop.tryGetValue(dialogContext.state)
+              if (!error) {
+                clone[key] = value
+              }
+            } else {
+              clone[key] = prop
+            }
+          }
+        }
+
+        return clone
+      }
+    }
+
+    return {}
+  }
+
+  /**
+     * Override to find the dialog instance referenced by the scope.
+     *
+     * @param dialogContext Current dialog context.
+     * @returns The dialog instance referenced by the scope.
+     */
+  protected onFindDialog (dialogContext: DialogContext): Dialog | undefined {
+    return dialogContext.findDialog(dialogContext.activeDialog.id)
+  }
+}
+
+function isExpression (prop: any): prop is ExpressionResolver {
+  return typeof prop === 'object' && typeof prop['tryGetValue'] === 'function'
+}
+
+interface ExpressionResolver {
+  tryGetValue(data: object): { value: any; error: Error };
+}

package/src/memory/scopes/conversationMemoryScope.ts

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

package/src/memory/scopes/dialogClassMemoryScope.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ClassMemoryScope } from './classMemoryScope'
+import { ScopePath } from '../scopePath'
+import { DialogContext } from '../../dialogContext'
+import { Dialog } from '../../dialog'
+import { DialogContainer } from '../../dialogContainer'
+
+export class DialogClassMemoryScope extends ClassMemoryScope {
+  /**
+     * Initializes a new instance of the DialogClassMemoryScope class.
+     */
+  constructor () {
+    super(ScopePath.dialogClass)
+  }
+
+  /**
+     * @protected
+     * @param dialogContext The DialogContext object for this turn.
+     * @returns The current Dialog.
+     */
+  protected onFindDialog (dialogContext: DialogContext): Dialog | undefined {
+    // Is the active dialog a container?
+    const dialog = dialogContext.findDialog(dialogContext.activeDialog.id)
+    if (dialog && dialog instanceof DialogContainer) {
+      return dialog
+    }
+
+    // Return parent dialog if there is one?
+    const parent = dialogContext.parent
+    if (parent && parent.activeDialog) {
+      const parentDialog = parent.findDialog(parent.activeDialog.id)
+      if (parentDialog) {
+        return parentDialog
+      }
+    }
+
+    // Fallback to returning current dialog
+    return dialog
+  }
+}

package/src/memory/scopes/dialogContextMemoryScope.ts

@@ -0,0 +1,51 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { DialogContext } from '../../dialogContext'
+import { MemoryScope } from './memoryScope'
+import { ScopePath } from '../scopePath'
+
+export class DialogContextMemoryScope extends MemoryScope {
+  /**
+     * Initializes a new instance of the `DialogContextMemoryScope` class.
+     */
+  constructor () {
+    super(ScopePath.dialogContext, false)
+  }
+
+  /**
+     * Gets the backing memory for this scope.
+     *
+     * @param dialogContext The `DialogContext` object for this turn.
+     * @returns Memory for the scope.
+     */
+  getMemory (dialogContext: DialogContext): Record<'stack' | 'activeDialog' | 'parent', unknown> {
+    const stack = []
+    let currentDialogContext: DialogContext | undefined = dialogContext
+
+    // go to leaf node
+    while (currentDialogContext.child) {
+      currentDialogContext = currentDialogContext.child
+    }
+
+    while (currentDialogContext) {
+      for (let i = currentDialogContext.stack.length - 1; i >= 0; i--) {
+        const item = currentDialogContext.stack[i]
+        // filter out ActionScope items because they are internal bookkeeping.
+        if (!item.id.startsWith('ActionScope[')) {
+          stack.push(item.id)
+        }
+      }
+
+      currentDialogContext = currentDialogContext.parent
+    }
+
+    return {
+      stack,
+      activeDialog: dialogContext.activeDialog && dialogContext.activeDialog.id,
+      parent: dialogContext.parent && dialogContext.parent.activeDialog && dialogContext.parent.activeDialog.id,
+    }
+  }
+}

package/src/memory/scopes/dialogMemoryScope.ts

@@ -0,0 +1,79 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { MemoryScope } from './memoryScope'
+import { ScopePath } from '../scopePath'
+import { DialogContext } from '../../dialogContext'
+import { DialogContainer } from '../../dialogContainer'
+
+export class DialogMemoryScope extends MemoryScope {
+  /**
+     * Initializes a new instance of the DialogMemoryScope class.
+     */
+  constructor () {
+    super(ScopePath.dialog)
+  }
+
+  /**
+     * Gets the backing memory for this scope.
+     *
+     * @param dialogContext The DialogContext object for this turn.
+     * @returns The memory for the scope.
+     */
+  getMemory (dialogContext: DialogContext): object {
+    // If active dialog is a container dialog then "dialog" binds to it.
+    // Otherwise the "dialog" will bind to the dialogs parent assuming it
+    // is a container.
+    let parent: DialogContext = dialogContext
+    if (!this.isContainer(parent) && parent.parent && this.isContainer(parent.parent)) {
+      parent = parent.parent
+    }
+
+    // If there's no active dialog then return undefined.
+    return parent.activeDialog ? parent.activeDialog.state : {}
+  }
+
+  /**
+     * Changes the backing object for the memory scope.
+     *
+     * @param dialogContext The DialogContext object for this turn.
+     * @param memory Memory object to set for the scope.
+     */
+  setMemory (dialogContext: DialogContext, memory: object): void {
+    if (memory === undefined) {
+      throw new Error('DialogMemoryScope.setMemory: undefined memory object passed in.')
+    }
+
+    // If active dialog is a container dialog then "dialog" binds to it.
+    // Otherwise the "dialog" will bind to the dialogs parent assuming it
+    // is a container.
+    let parent: DialogContext = dialogContext
+    if (!this.isContainer(parent) && parent.parent && this.isContainer(parent.parent)) {
+      parent = parent.parent
+    }
+
+    // If there's no active dialog then throw an error.
+    if (!parent.activeDialog) {
+      throw new Error('DialogMemoryScope.setMemory: no active dialog found.')
+    }
+
+    parent.activeDialog.state = memory
+  }
+
+  /**
+     * @private
+     * @param dialogContext The DialogContext object for this turn.
+     * @returns A boolean indicating whether is a cointainer or not.
+     */
+  private isContainer (dialogContext: DialogContext): boolean {
+    if (dialogContext !== undefined && dialogContext.activeDialog !== undefined) {
+      const dialog = dialogContext.findDialog(dialogContext.activeDialog.id)
+      if (dialog instanceof DialogContainer) {
+        return true
+      }
+    }
+
+    return false
+  }
+}

package/src/memory/scopes/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export * from './agentStateMemoryScope'
+export * from './classMemoryScope'
+export * from './conversationMemoryScope'
+export * from './dialogClassMemoryScope'
+export * from './dialogContextMemoryScope'
+export * from './dialogMemoryScope'
+export * from './memoryScope'
+export * from './settingsMemoryScope'
+export * from './thisMemoryScope'
+export * from './turnMemoryScope'
+export * from './userMemoryScope'

package/src/memory/scopes/memoryScope.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { DialogContext } from '../../dialogContext'
+
+/**
+ * Abstract base class for all memory scopes.
+ */
+export abstract class MemoryScope {
+  /**
+     * Initializes a new instance of the MemoryScope class.
+     *
+     * @param name Name of the scope.
+     * @param includeInSnapshot Boolean value indicating whether this memory
+     * should be included in snapshot. Default value is true.
+     */
+  constructor (name: string, includeInSnapshot = true) {
+    this.includeInSnapshot = includeInSnapshot
+    this.name = name
+  }
+
+  readonly name: string
+  readonly includeInSnapshot: boolean
+
+  /**
+     * Get the backing memory for this scope
+     *
+     * @param dialogContext Current dialog context.
+     * @returns memory for the scope
+     */
+  abstract getMemory (dialogContext: DialogContext): object
+
+  /**
+     * Changes the backing object for the memory scope.
+     *
+     * @param _dialogContext Current dialog context
+     * @param _memory memory to assign
+     */
+  setMemory (_dialogContext: DialogContext, _memory: object): void {
+    throw new Error(`MemoryScope.setMemory: The '${this.name}' memory scope is read-only.`)
+  }
+
+  /**
+     * Loads a scopes backing memory at the start of a turn.
+     *
+     * @param _dialogContext Current dialog context.
+     */
+  async load (_dialogContext: DialogContext): Promise<void> {
+    // No initialization by default.
+  }
+
+  /**
+     * Saves a scopes backing memory at the end of a turn.
+     *
+     * @param _dialogContext Current dialog context.
+     */
+  async saveChanges (_dialogContext: DialogContext): Promise<void> {
+    // No initialization by default.
+  }
+
+  /**
+     * Deletes the backing memory for a scope.
+     *
+     * @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.`)
+  }
+}