@microsoft/agents-hosting 0.6.21-g3c2261b2fc → 1.0.0-ge4831811bf

package/src/headerPropagation.ts

@@ -0,0 +1,129 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * A class that implements the HeaderPropagationCollection interface.
+ * It filters the incoming request headers based on the definition provided and loads them into the outgoing headers collection.
+ */
+export class HeaderPropagation implements HeaderPropagationCollection {
+  private _incomingRequests: Record<string, string>
+  private _outgoingHeaders: Record<string, string> = {}
+
+  private _headersToPropagate = ['x-ms-correlation-id']
+
+  public get incoming (): Record<string, string> {
+    return this._incomingRequests
+  }
+
+  public get outgoing (): Record<string, string> {
+    return this._outgoingHeaders
+  }
+
+  constructor (headers: Record<string, string | string[] | undefined>) {
+    if (!headers) {
+      throw new Error('Headers must be provided.')
+    }
+
+    this._incomingRequests = this.normalizeHeaders(headers)
+    this.propagate(this._headersToPropagate)
+  }
+
+  propagate (headers: string[]) {
+    for (const key of headers ?? []) {
+      const lowerKey = key.toLowerCase()
+      if (this._incomingRequests[lowerKey] && !this._outgoingHeaders[lowerKey]) {
+        this._outgoingHeaders[lowerKey] = this._incomingRequests[lowerKey]
+      }
+    }
+  }
+
+  add (headers: Record<string, string>) {
+    for (const [key, value] of Object.entries(headers ?? {})) {
+      const lowerKey = key.toLowerCase()
+      if (!this._incomingRequests[lowerKey] && !this._outgoingHeaders[lowerKey]) {
+        this._outgoingHeaders[lowerKey] = value
+      }
+    }
+  }
+
+  concat (headers: Record<string, string>) {
+    for (const [key, value] of Object.entries(headers ?? {})) {
+      const lowerKey = key.toLowerCase()
+      if (this._incomingRequests[lowerKey] && !this._headersToPropagate.includes(lowerKey)) {
+        this._outgoingHeaders[lowerKey] = `${this._outgoingHeaders[lowerKey] ?? this._incomingRequests[lowerKey]} ${value}`.trim()
+      }
+    }
+  }
+
+  override (headers: Record<string, string>) {
+    for (const [key, value] of Object.entries(headers ?? {})) {
+      const lowerKey = key.toLowerCase()
+      if (!this._headersToPropagate.includes(lowerKey)) {
+        this._outgoingHeaders[lowerKey] = value
+      }
+    }
+  }
+
+  /**
+   * Normalizes the headers by lowercasing the keys and ensuring the values are strings.
+   * @param headers The headers to normalize.
+   * @returns A new object with normalized headers.
+   */
+  private normalizeHeaders (headers: Record<string, string | string[] | undefined>) {
+    return Object.entries(headers).reduce((acc, [key, value]) => {
+      if (value) {
+        acc[key.toLowerCase()] = Array.isArray(value) ? value.join(' ') : value
+      }
+      return acc
+    }, {} as Record<string, string>)
+  }
+}
+
+/**
+ * A function type that defines how headers should be propagated.
+ */
+export interface HeaderPropagationDefinition {
+  (headers: HeaderPropagationCollection): void
+}
+
+/**
+ * Defines the interface for managing header propagation.
+ */
+export interface HeaderPropagationCollection {
+  /**
+   * The collection of incoming headers from the incoming request.
+   * @remarks This collection is built based on the headers received in the request.
+   */
+  incoming: Record<string, string>
+  /**
+   * The collection of headers that will be propagated to outgoing requests.
+   * @remarks This collection is built based on the incoming headers and the definition provided.
+   */
+  outgoing: Record<string, string>
+  /**
+   * Propagates the incoming header value to the outgoing collection based on the header definition key.
+   * @param headers List of header keys to propagate.
+   * @remarks If the header does not exist in the incoming headers, it will be ignored.
+   */
+  propagate(headers: string[]): void
+  /**
+   * Adds a header definition to the outgoing collection.
+   * @param headers Headers to add to the outgoing collection.
+   * @remarks If the header already exists, it will not be added.
+   */
+  add(headers: Record<string, string>): void
+  /**
+   * Concatenates a header definition to the outgoing collection.
+   * @param headers Headers to concatenate to the outgoing collection.
+   * @remarks If the header does not exist in the incoming headers, it will be ignored. Unless the header is already present in the outgoing collection.
+   */
+  concat(headers: Record<string, string>): void
+  /**
+   * Overrides a header definition in the outgoing collection.
+   * @param headers Headers to override in the outgoing collection.
+   * @remarks If the header does not exist in the incoming headers, it will be added to the outgoing collection.
+   */
+  override(headers: Record<string, string>): void
+}

package/src/oauth/userTokenClient.ts

@@ -22,43 +22,62 @@ export class UserTokenClient {
    */
   constructor (private msAppId: string) {
     const baseURL = 'https://api.botframework.com'
-    const axiosInstance = axios.create({
+    this.client = axios.create({
       baseURL,
       headers: {
         Accept: 'application/json',
         'User-Agent': getProductInfo(),
       }
     })
-    // axiosInstance.defaults.headers.common.Authorization = `Bearer ${token}`
-    axiosInstance.interceptors.response.use(
+
+    this.client.interceptors.request.use((config) => {
+      const { method, url, data, headers, params } = config
+      const { Authorization, authorization, ...headersToLog } = headers || {}
+      logger.debug('Request: ', {
+        host: this.client.getUri(),
+        url,
+        data,
+        method,
+        params,
+        headers: headersToLog
+      })
+      return config
+    })
+
+    this.client.interceptors.response.use(
       (config) => {
-        const { status, statusText, config: requestConfig } = config
+        const { status, statusText, config: requestConfig, headers } = config
+        const { Authorization, authorization, ...headersToLog } = headers || {}
+        const { token, ...redactedData } = requestConfig?.data || {}
         logger.debug('Response: ', {
           status,
           statusText,
-          host: axiosInstance.getUri(),
+          host: this.client.getUri(),
           url: requestConfig?.url,
-          data: config.config.data,
+          data: redactedData,
           method: requestConfig?.method,
+          headers: headersToLog
         })
         return config
       },
       (error) => {
         const { code, status, message, stack, response } = error
-        if (status !== 404) {
-          const errorDetails = {
-            code,
-            host: axiosInstance.getUri(),
-            url: error.config.url,
-            method: error.config.method,
-            data: error.config.data,
-            message: message + JSON.stringify(response?.data),
-            stack,
-          }
+        const { headers } = response || {}
+        const errorDetails = {
+          code,
+          host: this.client.getUri(),
+          url: error.config.url,
+          method: error.config.method,
+          data: error.config.data,
+          message: message + JSON.stringify(response?.data),
+          headers,
+          stack,
+        }
+        logger.debug('Response error: ', errorDetails)
+        if (errorDetails.url === '/api/usertoken/GetToken' && status !== 404) {
           return Promise.reject(errorDetails)
         }
       })
-    this.client = axiosInstance
   }
 
   /**

package/src/state/agentState.ts

@@ -44,8 +44,8 @@ export interface CustomKey {
 }
 
 /**
- * Manages the state of an Agent across turns in a conversation.
- *
+ * @summary Manages the state of an Agent across turns in a conversation.
+ * @remarks
  * AgentState provides functionality to persist and retrieve state data using
  * a storage provider. It handles caching state in the turn context for performance,
  * calculating change hashes to detect modifications, and managing property accessors

package/src/state/agentStatePropertyAccesor.ts

@@ -73,7 +73,7 @@ export interface StatePropertyAccessor<T = any> {
 }
 
 /**
- * Provides typed access to an Agent state property with automatic state loading and persistence management.
+ * @summary Provides typed access to an Agent state property with automatic state loading and persistence management.
  *
  * @remarks
  * AgentStatePropertyAccessor simplifies working with persisted state by abstracting
@@ -86,9 +86,9 @@ export interface StatePropertyAccessor<T = any> {
  * - **Memory Management**: Efficient in-memory caching with explicit persistence control
  * - **Custom Keys**: Support for custom storage keys for advanced scenarios
  *
- * ## Key Features
+ * ### Key Features
  *
- * ### Type Safety
+ * #### Type Safety
  * The accessor provides compile-time type checking when using TypeScript:
  * ```typescript
  * interface UserProfile {
@@ -98,7 +98,7 @@ export interface StatePropertyAccessor<T = any> {
  * const userProfile = userState.createProperty<UserProfile>("userProfile");
  * ```
  *
- * ### Automatic Default Value Handling
+ * #### Automatic Default Value Handling
  * When a property doesn't exist, default values are automatically cloned and stored:
  * ```typescript
  * // If userProfile doesn't exist, the default will be cloned and saved
@@ -108,7 +108,7 @@ export interface StatePropertyAccessor<T = any> {
  * });
  * ```
  *
- * ### Explicit Persistence Control
+ * #### Explicit Persistence Control
  * Changes are kept in memory until explicitly persisted:
  * ```typescript
  * // Modify the state
@@ -120,9 +120,9 @@ export interface StatePropertyAccessor<T = any> {
  * await userState.saveChanges(context);
  * ```
  *
- * ## Usage Examples
+ * ### Usage Examples
  *
- * ### Basic Usage
+ * @example Basic Usage
  * ```typescript
  * // Create a property accessor
  * const userProfile = userState.createProperty<UserProfile>("userProfile");
@@ -141,7 +141,7 @@ export interface StatePropertyAccessor<T = any> {
  * await userState.saveChanges(context); // Persist to storage
  * ```
  *
- * ### Working with Primitive Types
+ * @example Working with Primitive Types
  * ```typescript
  * const counterProperty = userState.createProperty<number>("counter");
  *
@@ -151,7 +151,7 @@ export interface StatePropertyAccessor<T = any> {
  * await userState.saveChanges(context);
  * ```
  *
- * ### Conditional Logic
+ * @example Conditional Logic
  * ```typescript
  * const settingsProperty = userState.createProperty<Settings>("settings");
  *
@@ -163,7 +163,7 @@ export interface StatePropertyAccessor<T = any> {
  * }
  * ```
  *
- * ### Custom Storage Keys
+ * @example Custom Storage Keys
  * ```typescript
  * // Store state with a custom key for multi-tenant scenarios
  * const customKey = { key: `tenant_${tenantId}` };
@@ -171,7 +171,7 @@ export interface StatePropertyAccessor<T = any> {
  * await dataProperty.set(context, updatedData, customKey);
  * ```
  *
- * ## Important Notes
+ * ### Important Notes
  *
  * - **Thread Safety**: This class is not thread-safe. Ensure proper synchronization in concurrent scenarios.
  * - **Memory Usage**: State objects are kept in memory until the context is disposed.
@@ -206,20 +206,19 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
   constructor (protected readonly state: AgentState, public readonly name: string) { }
 
   /**
-   * Deletes the property from the state storage.
-   *
+   * @summary Deletes the property from the state storage.
+   * @remarks
    * This operation removes the property from the in-memory state object but does not
    * automatically persist the change to the underlying storage. You must call
    * `state.saveChanges(context)` afterwards to persist the deletion.
    *
-   * @remarks
    * - If the property doesn't exist, this operation is a no-op
    * - The deletion only affects the in-memory state until `saveChanges()` is called
    * - After deletion, subsequent `get()` calls will return `undefined` (or the default value if provided)
    *
    * @param context The turn context for the current conversation turn
    * @param customKey Optional custom key for accessing state in a specific storage location.
-   *                  Useful for multi-tenant scenarios or when state needs to be partitioned.
+   * Useful for multi-tenant scenarios or when state needs to be partitioned.
    *
    * @returns A promise that resolves when the delete operation is complete
    *
@@ -252,15 +251,14 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
   }
 
   /**
-   * Retrieves the value of the property from state storage.
-   *
+   * @summary Retrieves the value of the property from state storage.
+   * @remarks
    * This method provides intelligent default value handling:
    * - If the property exists, its value is returned
    * - If the property doesn't exist and a default value is provided, the default is deep cloned,
    *   stored in state, and returned
    * - If the property doesn't exist and no default is provided, `undefined` is returned
    *
-   * @remarks
    * **Deep Cloning**: Default values are deep cloned using JSON serialization to prevent
    * reference sharing issues. This means:
    * - Functions, symbols, and circular references will be lost
@@ -331,13 +329,12 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
   }
 
   /**
-   * Sets the value of the property in state storage.
-   *
+   * @summary Sets the value of the property in state storage.
+   * @remarks
    * This operation updates the property in the in-memory state object but does not
    * automatically persist the change to the underlying storage. You must call
    * `state.saveChanges(context)` afterwards to persist the changes.
    *
-   * @remarks
    * **Memory vs Storage**: Changes are immediately reflected in memory and will be
    * available to subsequent `get()` calls within the same context, but are not
    * persisted to storage until `saveChanges()` is called.

package/src/storage/fileStorage.ts

@@ -8,7 +8,7 @@ import fs from 'fs'
 import { Storage, StoreItem } from './storage'
 
 /**
- * A file-based storage implementation that persists data to the local filesystem.
+ * @summary A file-based storage implementation that persists data to the local filesystem.
  *
  * @remarks
  * FileStorage stores all data in a single JSON file named 'state.json' within a specified folder.
@@ -19,6 +19,16 @@ import { Storage, StoreItem } from './storage'
  * can be any JSON-serializable data. All operations are synchronous file I/O operations
  * wrapped in Promise interfaces to match the Storage contract.
  *
+ * ### Warning
+ * This implementation does not provide:
+ * - Thread safety for concurrent access
+ * - Optimistic concurrency control (eTag support)
+ * - Atomic operations across multiple keys
+ * - Scale for large datasets
+ *
+ * For production scenarios requiring these features, consider using
+ * database-backed storage implementations instead.
+ *
  * @example
  * ```typescript
  * const storage = new FileStorage('./data');
@@ -37,15 +47,7 @@ import { Storage, StoreItem } from './storage'
  * await storage.delete(['conversation456']);
  * ```
  *
- * @warning
- * This implementation does not provide:
- * - Thread safety for concurrent access
- * - Optimistic concurrency control (eTag support)
- * - Atomic operations across multiple keys
- * - Scale for large datasets
- *
- * For production scenarios requiring these features, consider using
- * database-backed storage implementations instead.
+
  */
 export class FileStorage implements Storage {
   private _folder: string

package/src/transcript/transcriptLogger.ts

@@ -31,7 +31,7 @@ export interface TranscriptInfo {
 
 /**
  * Paged result of items.
- * @template T - The type of items in the paged result.
+ * @typeParam T - The type of items in the paged result.
  */
 export interface PagedResult<T> {
   /**