@microsoft/agents-hosting 0.1.49

package/src/state/agentState.ts

@@ -0,0 +1,142 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Storage, StorageKeyFactory, StoreItem } from '../storage/storage'
+import { TurnContext } from '../turnContext'
+import { createHash } from 'node:crypto'
+import { AgentStatePropertyAccessor } from './agentStatePropertyAccesor'
+import { debug } from '../logger'
+
+const logger = debug('agents:state')
+
+export interface CachedAgentState {
+  state: { [id: string]: any }
+  hash: string
+}
+
+/**
+ * Manages the state of an Agent.
+ */
+export class AgentState {
+  private readonly stateKey = Symbol('state')
+
+  /**
+    * Creates a new instance of AgentState.
+    * @param storage The storage provider.
+    * @param storageKey The storage key factory.
+    */
+  constructor (protected storage: Storage, protected storageKey: StorageKeyFactory) { }
+
+  /**
+   * Creates a property accessor for the specified property.
+   * @param name The name of the property.
+   * @returns A property accessor for the specified property.
+   */
+  createProperty<T = any>(name: string): AgentStatePropertyAccessor<T> {
+    const prop: AgentStatePropertyAccessor<T> = new AgentStatePropertyAccessor<T>(this, name)
+    return prop
+  }
+
+  /**
+   * Loads the state from storage.
+   * @param context The turn context.
+   * @param force Whether to force loading the state.
+   * @returns A promise that resolves to the loaded state.
+   */
+  public async load (context: TurnContext, force = false): Promise<any> {
+    const cached: CachedAgentState = context.turnState.get(this.stateKey)
+
+    if (force || !cached || !cached.state) {
+      const key = await this.storageKey(context)
+      logger.info(`Reading storage with key ${key}`)
+      const storedItem = await this.storage.read([key])
+
+      const state: any = storedItem[key] || {}
+      const hash: string = this.calculateChangeHash(state)
+      context.turnState.set(this.stateKey, { state, hash })
+
+      return state
+    }
+
+    return cached.state
+  }
+
+  /**
+   * Saves the state to storage.
+   * @param context The turn context.
+   * @param force Whether to force saving the state.
+   * @returns A promise that resolves when the save operation is complete.
+   */
+  public async saveChanges (context: TurnContext, force = false): Promise<void> {
+    let cached: CachedAgentState = context.turnState.get(this.stateKey)
+    if (force || (cached && cached.hash !== this.calculateChangeHash(cached?.state))) {
+      if (!cached) {
+        cached = { state: {}, hash: '' }
+      }
+      cached.state.eTag = '*'
+      const changes: StoreItem = {} as StoreItem
+
+      const key = await this.storageKey(context)
+      changes[key] = cached.state
+
+      logger.info(`Writing storage with key ${key}`)
+      await this.storage.write(changes)
+      cached.hash = this.calculateChangeHash(cached.state)
+      context.turnState.set(this.stateKey, cached)
+    }
+  }
+
+  /**
+   * Clears the state from the turn context.
+   * @param context The turn context.
+   * @returns A promise that resolves when the clear operation is complete.
+   */
+  public async clear (context: TurnContext): Promise<void> {
+    const emptyObjectToForceSave = { state: {}, hash: '' }
+    context.turnState.set(this.stateKey, emptyObjectToForceSave)
+  }
+
+  /**
+   * Deletes the state from storage.
+   * @param context The turn context.
+   * @returns A promise that resolves when the delete operation is complete.
+   */
+  public async delete (context: TurnContext): Promise<void> {
+    if (context.turnState.has(this.stateKey)) {
+      context.turnState.delete(this.stateKey)
+    }
+    const key = await this.storageKey(context)
+    logger.info(`Deleting storage with key ${key}`)
+    await this.storage.delete([key])
+  }
+
+  /**
+   * Gets the state from the turn context.
+   * @param context The turn context.
+   * @returns The state, or undefined if the state is not found.
+   */
+  public get (context: TurnContext): any | undefined {
+    const cached: CachedAgentState = context.turnState.get(this.stateKey)
+
+    return typeof cached === 'object' && typeof cached.state === 'object' ? cached.state : undefined
+  }
+
+  /**
+   * Calculates the change hash for the specified item.
+   * @param item The item to calculate the hash for.
+   * @returns The calculated hash.
+   */
+  private readonly calculateChangeHash = (item: StoreItem): string => {
+    const { eTag, ...rest } = item
+
+    // TODO review circular json structure
+    const result = JSON.stringify(rest)
+
+    const hash = createHash('sha256', { encoding: 'utf-8' })
+    const hashed = hash.update(result).digest('hex')
+
+    return hashed
+  }
+}

package/src/state/agentStatePropertyAccesor.ts

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TurnContext } from '../turnContext'
+import { AgentState } from './agentState'
+
+/**
+ * Provides access to an Agent state property.
+ */
+export class AgentStatePropertyAccessor<T = any> {
+  /**
+   * Creates a new instance of AgentStatePropertyAccessor.
+   * @param state The agent state.
+   * @param name The name of the property.
+   */
+  constructor (protected readonly state: AgentState, public readonly name: string) { }
+
+  /**
+   * Deletes the property from the state.
+   * @param context The turn context.
+   * @returns A promise that resolves when the delete operation is complete.
+   */
+  async delete (context: TurnContext): Promise<void> {
+    const obj: any = await this.state.load(context)
+    if (Object.prototype.hasOwnProperty.call(obj, this.name)) {
+      delete obj[this.name]
+    }
+  }
+
+  /**
+   * Gets the value of the property from the state.
+   * @param context The turn context.
+   * @param defaultValue The default value to return if the property is not found.
+   * @returns A promise that resolves to the value of the property.
+   */
+  async get (context: TurnContext, defaultValue?: T): Promise<T> {
+    const obj: any = await this.state.load(context)
+    if (!Object.prototype.hasOwnProperty.call(obj, this.name) && defaultValue !== undefined) {
+      const clone: any =
+        typeof defaultValue === 'object' || Array.isArray(defaultValue)
+          ? JSON.parse(JSON.stringify(defaultValue))
+          : defaultValue
+      obj[this.name] = clone
+    }
+
+    return obj[this.name]
+  }
+
+  /**
+   * Sets the value of the property in the state.
+   * @param context The turn context.
+   * @param value The value to set.
+   * @returns A promise that resolves when the set operation is complete.
+   */
+  async set (context: TurnContext, value: T): Promise<void> {
+    const obj: any = await this.state.load(context)
+    obj[this.name] = value
+  }
+}

package/src/state/conversationState.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AgentState } from './agentState'
+import { Storage } from '../storage/storage'
+import { TurnContext } from '../turnContext'
+import { Activity } from '@microsoft/agents-activity'
+
+/**
+ * Manages the state of a conversation.
+ */
+export class ConversationState extends AgentState {
+  /**
+   * Creates a new instance of ConversationState.
+   * @param storage The storage provider.
+   */
+  constructor (storage: Storage, private readonly namespace: string = '') {
+    super(storage, (context: TurnContext) => {
+      const key: string = this.getStorageKey(context)
+
+      return key ?? new Error('ConversationState: overridden getStorageKey method did not return a key.')
+    })
+  }
+
+  private getStorageKey (context: TurnContext): string {
+    const activity: Activity = context.activity
+    const channelId = activity.channelId
+    const conversationId = activity && (activity.conversation != null) && activity.conversation.id ? activity.conversation.id : undefined
+
+    if (!channelId) {
+      throw new Error('missing activity.channelId')
+    }
+
+    if (!conversationId) {
+      throw new Error('missing activity.conversation.id')
+    }
+
+    return `${channelId}/conversations/${conversationId}/${this.namespace}`
+  }
+}

package/src/state/index.ts

@@ -0,0 +1,4 @@
+export * from './userState'
+export * from './conversationState'
+export * from './agentStatePropertyAccesor'
+export * from './agentState'

package/src/state/userState.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AgentState } from './agentState'
+import { Storage } from '../storage/storage'
+import { TurnContext } from '../turnContext'
+import { Activity } from '@microsoft/agents-activity'
+
+/**
+ * Manages the state of a user.
+ */
+export class UserState extends AgentState {
+  /**
+    * Creates a new instance of UserState.
+    * @param storage The storage provider.
+    */
+  constructor (storage: Storage, private readonly namespace: string = '') {
+    super(storage, (context: TurnContext) => {
+      const key: string = this.getStorageKey(context)
+
+      return key ?? new Error('UserState: overridden getStorageKey method did not return a key.')
+    })
+  }
+
+  private getStorageKey (context: TurnContext): string {
+    const activity: Activity = context.activity
+
+    const channelId = activity.channelId
+    const userId = activity && (activity.from != null) && activity.from.id ? activity.from.id : undefined
+
+    if (!channelId) {
+      throw new Error('missing activity.channelId')
+    }
+
+    if (!userId) {
+      throw new Error('missing activity.from.id')
+    }
+
+    return `${channelId}/users/${userId}/${this.namespace}`
+  }
+}

package/src/statusCodes.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export enum StatusCodes {
+  OK = 200,
+  CREATED = 201,
+  MULTIPLE_CHOICES = 300,
+  BAD_REQUEST = 400,
+  UNAUTHORIZED = 401,
+  NOT_FOUND = 404,
+  METHOD_NOT_ALLOWED = 405,
+  CONFLICT = 409,
+  PRECONDITION_FAILED = 412,
+  UPGRADE_REQUIRED = 426,
+  INTERNAL_SERVER_ERROR = 500,
+  NOT_IMPLEMENTED = 501,
+  BAD_GATEWAY = 502,
+}

package/src/storage/index.ts

@@ -0,0 +1,2 @@
+export * from './storage'
+export * from './memoryStorage'

package/src/storage/memoryStorage.ts

@@ -0,0 +1,105 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Storage, StoreItem } from './storage'
+import { debug } from '../logger'
+
+const logger = debug('agents:memory-storage')
+
+/**
+ * A simple in-memory storage provider.
+ */
+export class MemoryStorage implements Storage {
+  private static instance: MemoryStorage
+  private etag: number = 1
+
+  /**
+   * Creates a new instance of the MemoryStorage class.
+   * @param memory An optional initial memory store.
+   */
+  constructor (private memory: { [k: string]: string } = {}) { }
+
+  /**
+   * Gets a single instance of the MemoryStorage class.
+   */
+  static getSingleInstance (): MemoryStorage {
+    if (!MemoryStorage.instance) {
+      MemoryStorage.instance = new MemoryStorage()
+    }
+    return MemoryStorage.instance
+  }
+
+  /**
+   * Reads storage items from memory.
+   * @param keys The keys of the items to read.
+   * @returns A promise that resolves to the read items.
+   * @throws Will throw an error if keys are not provided.
+   */
+  async read (keys: string[]): Promise<StoreItem> {
+    if (!keys || keys.length === 0) {
+      throw new ReferenceError('Keys are required when reading.')
+    }
+
+    const data: StoreItem = {}
+    for (const key of keys) {
+      logger.info(`Reading key: ${key}`)
+      const item = this.memory[key]
+      if (item) {
+        data[key] = JSON.parse(item)
+      }
+    }
+
+    return data
+  }
+
+  /**
+   * Writes storage items to memory.
+   * @param changes The items to write.
+   * @returns A promise that resolves when the write operation is complete.
+   * @throws Will throw an error if changes are not provided.
+   */
+  async write (changes: StoreItem): Promise<void> {
+    if (!changes || changes.length === 0) {
+      throw new ReferenceError('Changes are required when writing.')
+    }
+
+    for (const [key, newItem] of Object.entries(changes)) {
+      logger.info(`Writing key: ${key}`)
+      const oldItemStr = this.memory[key]
+      if (!oldItemStr || newItem.eTag === '*' || !newItem.eTag) {
+        this.saveItem(key, newItem)
+      } else {
+        const oldItem = JSON.parse(oldItemStr)
+        if (newItem.eTag === oldItem.eTag) {
+          this.saveItem(key, newItem)
+        } else {
+          throw new Error(`Storage: error writing "${key}" due to eTag conflict.`)
+        }
+      }
+    }
+  }
+
+  /**
+   * Deletes storage items from memory.
+   * @param keys The keys of the items to delete.
+   * @returns A promise that resolves when the delete operation is complete.
+   */
+  async delete (keys: string[]): Promise<void> {
+    logger.info(`Deleting keys: ${keys.join(', ')}`)
+    for (const key of keys) {
+      delete this.memory[key]
+    }
+  }
+
+  /**
+   * Saves an item to memory.
+   * @param key The key of the item to save.
+   * @param item The item to save.
+   */
+  private saveItem (key: string, item: unknown): void {
+    const clone = Object.assign({}, item, { eTag: (this.etag++).toString() })
+    this.memory[key] = JSON.stringify(clone)
+  }
+}

package/src/storage/storage.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TurnContext } from '../turnContext'
+
+/**
+ * Represents an item to be stored.
+ */
+export interface StoreItem {
+  eTag?: string
+  [key: string]: any
+}
+
+/**
+ * Represents a collection of store items.
+ */
+export interface StoreItems {
+  [key: string]: any;
+}
+
+/**
+ * A factory function to generate storage keys based on the context.
+ * @param context The TurnContext for the current turn of conversation.
+ * @returns A string key for storage.
+ */
+export type StorageKeyFactory = (context: TurnContext) => string
+
+/**
+ * Defines the interface for storage operations.
+ */
+export interface Storage {
+  /**
+   * Reads store items from storage.
+   * @param keys The keys of the items to read.
+   * @returns A promise that resolves to the store items.
+   */
+  read: (keys: string[]) => Promise<StoreItem>
+  /**
+   * Writes store items to storage.
+   * @param changes The items to write to storage.
+   * @returns A promise that resolves when the write operation is complete.
+   */
+  write: (changes: StoreItem) => Promise<void>
+  /**
+   * Deletes store items from storage.
+   * @param keys The keys of the items to delete.
+   * @returns A promise that resolves when the delete operation is complete.
+   */
+  delete: (keys: string[]) => Promise<void>
+}

package/src/tokenResponseEventName.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export const tokenResponseEventName = 'tokens/response'

package/src/transcript/consoleTranscriptLogger.ts

@@ -0,0 +1,20 @@
+import { Activity } from '@microsoft/agents-activity'
+import { TranscriptLogger } from './transcriptLogger'
+
+/**
+ * A transcript logger that logs activities to the console.
+ */
+export class ConsoleTranscriptLogger implements TranscriptLogger {
+  /**
+   * Logs an activity to the console.
+   * @param activity The activity to log.
+   * @throws Will throw an error if the activity is not provided.
+   */
+  logActivity (activity: Activity): void | Promise<void> {
+    if (!activity) {
+      throw new Error('Activity is required.')
+    }
+
+    console.log('Activity Log:', activity)
+  }
+}

package/src/transcript/index.ts

@@ -0,0 +1,4 @@
+export * from './transcriptLogger'
+export * from './transcriptStore'
+export * from './transcriptLoggerMiddleware'
+export * from './consoleTranscriptLogger'

package/src/transcript/transcriptLogger.ts

@@ -0,0 +1,45 @@
+import { Activity } from '@microsoft/agents-activity'
+
+/**
+ * Interface for logging activities to a transcript.
+ */
+export interface TranscriptLogger {
+  /**
+   * Logs an activity.
+   * @param activity - The activity to log.
+   */
+  logActivity(activity: Activity): void | Promise<void>;
+}
+
+/**
+ * Information about a transcript.
+ */
+export interface TranscriptInfo {
+  /**
+   * The ID of the channel.
+   */
+  channelId: string;
+  /**
+   * The ID of the transcript.
+   */
+  id: string;
+  /**
+   * The creation date of the transcript.
+   */
+  created: Date;
+}
+
+/**
+ * Paged result of items.
+ * @template T - The type of items in the paged result.
+ */
+export interface PagedResult<T> {
+  /**
+   * The items in the paged result.
+   */
+  items: T[];
+  /**
+   * The continuation token for pagination.
+   */
+  continuationToken?: string;
+}