@microsoft/agents-hosting 0.6.21-g3c2261b2fc → 0.6.22

package/dist/src/transcript/transcriptLogger.d.ts

@@ -28,7 +28,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> {
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@microsoft/agents-hosting",
-  "version": "0.6.21-g3c2261b2fc",
+  "version": "0.6.22",
   "homepage": "https://github.com/microsoft/Agents-for-js",
   "repository": {
     "type": "git",
@@ -21,7 +21,7 @@
   "dependencies": {
     "@azure/core-auth": "^1.10.0",
     "@azure/msal-node": "^3.6.0",
-    "@microsoft/agents-activity": "0.6.21-g3c2261b2fc",
+    "@microsoft/agents-activity": "0.6.22",
     "axios": "^1.10.0",
     "jsonwebtoken": "^9.0.2",
     "jwks-rsa": "^3.2.0"

package/src/app/adaptiveCards/adaptiveCardsActions.ts

@@ -34,7 +34,8 @@ enum AdaptiveCardInvokeResponseType {
 }
 
 /**
- * Represents a single search result item returned from an Adaptive Card search operation.
+ * @summary Represents a single search result item returned from an Adaptive Card search operation.
+ * @remarks
  * This interface defines the structure for search results that are displayed to users
  * when they perform searches within Adaptive Cards, such as typeahead or dropdown searches.
  *
@@ -48,7 +49,8 @@ enum AdaptiveCardInvokeResponseType {
  */
 export interface AdaptiveCardSearchResult {
   /**
-   * The display text shown to the user in the search results.
+   * @summary The display text shown to the user in the search results.
+   * @remarks
    * This is typically the human-readable label that appears in dropdowns,
    * typeahead suggestions, or search result lists.
    *
@@ -57,7 +59,8 @@ export interface AdaptiveCardSearchResult {
   title: string;
 
   /**
-   * The underlying value associated with this search result.
+   * @summary The underlying value associated with this search result.
+   * @remarks
    * This is usually the actual data value that gets selected when the user
    * chooses this result, such as an ID, email address, or other identifier.
    *
@@ -68,7 +71,7 @@ export interface AdaptiveCardSearchResult {
 
 /**
  * A class to handle Adaptive Card actions such as executing actions, submitting actions, and performing searches.
- * @template TState - The type of the TurnState used in the application.
+ * @typeParam TState - The type of the TurnState used in the application.
  */
 export class AdaptiveCardsActions<TState extends TurnState> {
   /**
@@ -86,7 +89,7 @@ export class AdaptiveCardsActions<TState extends TurnState> {
 
   /**
    * Registers a handler for the Action.Execute event.
-   * @template TData - The type of the data passed to the handler.
+   * @typeParam TData - The type of the data passed to the handler.
    * @param verb - A string, RegExp, RouteSelector, or an array of these to match the action verb.
    * @param handler - A function to handle the action execution.
    * @returns The Teams application instance.
@@ -171,7 +174,7 @@ export class AdaptiveCardsActions<TState extends TurnState> {
 
   /**
    * Registers a handler for the Action.Submit event.
-   * @template TData - The type of the data passed to the handler.
+   * @typeParam TData - The type of the data passed to the handler.
    * @param verb - A string, RegExp, RouteSelector, or an array of these to match the action verb.
    * @param handler - A function to handle the action submission.
    * @returns The Teams application instance.

package/src/app/adaptiveCards/query.ts

@@ -5,7 +5,7 @@
 
 /**
  * Represents a query with pagination and parameters.
- * @template TParams - The type of the query parameters.
+ * @typeParam TParams - The type of the query parameters.
  */
 export interface Query<TParams extends Record<string, any>> {
   /**

package/src/app/agentApplication.ts

@@ -28,7 +28,7 @@ const TYPING_TIMER_DELAY = 1000
 
 /**
  * Event handler function type for application events.
- * @template TState - The state type extending TurnState.
+ * @typeParam TState - The state type extending TurnState.
  * @param context - The turn context containing activity information.
  * @param state - The current turn state.
  * @returns A promise that resolves to a boolean indicating whether to continue execution.
@@ -36,9 +36,7 @@ const TYPING_TIMER_DELAY = 1000
 export type ApplicationEventHandler<TState extends TurnState> = (context: TurnContext, state: TState) => Promise<boolean>
 
 /**
- * Main application class for handling agent conversations and routing.
- *
- * @template TState - The state type extending TurnState.
+ * @summary Main application class for handling agent conversations and routing.
  *
  * @remarks
  * The AgentApplication class provides a framework for building conversational agents.
@@ -66,6 +64,8 @@ export type ApplicationEventHandler<TState extends TurnState> = (context: TurnCo
  *
  * await app.run(turnContext);
  * ```
+ *
+ * @typeParam TState - The state type extending TurnState.
  */
 export class AgentApplication<TState extends TurnState> {
   protected readonly _options: AgentApplicationOptions<TState>
@@ -79,7 +79,7 @@ export class AgentApplication<TState extends TurnState> {
   private readonly _adaptiveCards: AdaptiveCardsActions<TState>
 
   /**
-   * Creates a new instance of AgentApplication.
+   * @summary Creates a new instance of AgentApplication.
    *
    * @param options - Optional configuration options for the application.
    *
@@ -142,7 +142,7 @@ export class AgentApplication<TState extends TurnState> {
   }
 
   /**
-   * Gets the authorization instance for the application.
+   * @summary Gets the authorization instance for the application.
    *
    * @returns The authorization instance.
    * @throws Error if no authentication options were configured.
@@ -155,7 +155,7 @@ export class AgentApplication<TState extends TurnState> {
   }
 
   /**
-   * Gets the options used to configure the application.
+   * @summary Gets the options used to configure the application.
    *
    * @returns The application options.
    */
@@ -164,7 +164,7 @@ export class AgentApplication<TState extends TurnState> {
   }
 
   /**
-   * Gets the adapter used by the application.
+   * @summary Gets the adapter used by the application.
    *
    * @returns The adapter instance.
    */
@@ -173,7 +173,7 @@ export class AgentApplication<TState extends TurnState> {
   }
 
   /**
-   * Gets the adaptive cards actions handler for the application.
+   * @summary Gets the adaptive cards actions handler for the application.
    *
    * @returns The adaptive cards actions instance.
    *
@@ -766,7 +766,7 @@ export class AgentApplication<TState extends TurnState> {
   /**
    * Registers an extension with the application.
    *
-   * @template T - The extension type extending AgentExtension.
+   * @typeParam T - The extension type extending AgentExtension.
    * @param extension - The extension instance to register.
    * @param regcb - Callback function called after successful registration.
    * @throws Error if the extension is already registered.

package/src/app/agentApplicationBuilder.ts

@@ -11,7 +11,7 @@ import { TurnState } from './turnState'
 
 /**
  * Builder class for creating and configuring AgentApplication instances.
- * @template TState Type extending TurnState that will be used by the application
+ * @typeParam TState Type extending TurnState that will be used by the application
  */
 export class AgentApplicationBuilder<TState extends TurnState = TurnState> {
   protected _options: Partial<AgentApplicationOptions<TState>> = {}

package/src/app/agentApplicationOptions.ts

@@ -16,7 +16,7 @@ import { TurnState } from './turnState'
  * This interface defines all the configurable aspects of an agent's behavior,
  * including adapter settings, storage, authorization, and various feature flags.
  *
- * @template TState - The type of turn state that extends TurnState, allowing for
+ * @typeParam TState - The type of turn state that extends TurnState, allowing for
  * custom state management specific to your agent's needs.
  */
 export interface AgentApplicationOptions<TState extends TurnState> {

package/src/app/appMemory.ts

@@ -23,7 +23,7 @@ export interface AppMemory {
 
   /**
    * Gets a value from the specified path.
-   * @template TValue The expected type of the value
+   * @typeParam TValue The expected type of the value
    * @param path The path to get the value from
    * @returns The value at the specified path cast to type TValue
    */

package/src/app/appRoute.ts

@@ -15,7 +15,7 @@ import { TurnState } from './turnState'
  * a selector function that determines when the route should be activated with a handler
  * function that processes the matched activities.
  *
- * @template TState - The type of turn state that extends TurnState, allowing for
+ * @typeParam TState - The type of turn state that extends TurnState, allowing for
  *                    type-safe access to custom state properties within route handlers
  *
  * @example

package/src/app/extensions.ts

@@ -9,7 +9,7 @@ import { TurnState } from './turnState'
  * Represents an extension that adds channel-specific routing functionality to an agent application.
  * This class allows you to register routes that are only active for a specific channel.
  *
- * @template TState - The type of turn state that extends TurnState
+ * @typeParam TState - The type of turn state that extends TurnState
  */
 export class AgentExtension<TState extends TurnState> {
   /** The channel ID that this extension is associated with */

package/src/app/turnState.ts

@@ -40,7 +40,7 @@ export interface DefaultTempState {
 }
 
 /**
- * Base class defining a collection of turn state scopes.
+ * @summary Base class defining a collection of turn state scopes.
  * @remarks
  * Developers can create a derived class that extends `TurnState` to add additional state scopes.
  *
@@ -70,10 +70,10 @@ export interface DefaultTempState {
  *   }
  * }
  * ```
- * @template TConversationState - Type for conversation-scoped state
- * @template TUserState - Type for user-scoped state
- * @template TTempState - Type for temporary state that exists only for the current turn
- * @template TSSOState - Type for Single Sign-On (SSO) state
+ * @typeParam TConversationState - Type for conversation-scoped state
+ * @typeParam TUserState - Type for user-scoped state
+ * @typeParam TTempState - Type for temporary state that exists only for the current turn
+ * @typeParam TSSOState - Type for Single Sign-On (SSO) state
  */
 export class TurnState<
     TConversationState = DefaultConversationState,
@@ -248,7 +248,7 @@ export class TurnState<
   /**
    * Gets a value from state by dot-notation path.
    * Format: "scope.property" or just "property" (defaults to temp scope)
-   * @template TValue - The type of the value to retrieve
+   * @typeParam TValue - The type of the value to retrieve
    * @param path - The path to the value
    * @returns The value at the specified path
    */

package/src/app/turnStateProperty.ts

@@ -10,7 +10,7 @@ import { TurnState } from './turnState'
 
 /**
  * Maps an application's Turn State property to a State property.
- * @template T Optional. Type of the property being mapped. Defaults to any.
+ * @typeParam T Optional. Type of the property being mapped. Defaults to any.
  */
 export class TurnStateProperty<T = any> implements StatePropertyAccessor<T> {
   private readonly _state: TurnStateEntry
@@ -60,7 +60,7 @@ export class TurnStateProperty<T = any> implements StatePropertyAccessor<T> {
 
   /**
      * Replace's the state property value.
-     * @template T
+     * @typeParam T
      * @param {TurnContext} context The context object for the turn.
      * @param {T} value The value to assign to the state property.
      * @returns {Promise<void>} A promise that represents the work queued to execute.

package/src/auth/authConfiguration.ts

@@ -45,7 +45,15 @@ export interface AuthConfiguration {
   /**
    * The FIC (First-Party Integration Channel) client ID.
    */
-  FICClientId?: string
+  FICClientId?: string,
+
+  /**
+   * Entra Authentication Endpoint to use,  If not populated the Entra Public Cloud endpoint is assumed.
+   * This example of Public Cloud Endpoint is https://login.microsoftonline.com
+   @remarks
+   see also https://learn.microsoft.com/entra/identity-platform/authentication-national-cloud
+   */
+  authority?: string
 }
 
 /**
@@ -63,6 +71,7 @@ export interface AuthConfiguration {
  * FICClientId=your-FIC-client-id
  *
  * connectionName=your-connection-name
+ * authority=your-authority-endpoint
  * ```
  * @remarks
  * - `clientId` is required
@@ -71,6 +80,7 @@ export interface AuthConfiguration {
  */
 export const loadAuthConfigFromEnv: (cnxName?: string) => AuthConfiguration = (cnxName?: string) => {
   if (cnxName === undefined) {
+    const authority = process.env.authorityEndpoint ?? 'https://login.microsoftonline.com'
     if (process.env.clientId === undefined && process.env.NODE_ENV === 'production') {
       throw new Error('ClientId required in production')
     }
@@ -82,13 +92,15 @@ export const loadAuthConfigFromEnv: (cnxName?: string) => AuthConfiguration = (c
       certKeyFile: process.env.certKeyFile,
       connectionName: process.env.connectionName,
       FICClientId: process.env.FICClientId,
+      authority,
       issuers: [
         'https://api.botframework.com',
         `https://sts.windows.net/${process.env.tenantId}/`,
-        `https://login.microsoftonline.com/${process.env.tenantId}/v2.0`
-      ]
+        `${authority}/${process.env.tenantId}/v2.0`
+      ],
     }
   } else {
+    const authority = process.env[`${cnxName}_authorityEndpoint`] ?? 'https://login.microsoftonline.com'
     return {
       tenantId: process.env[`${cnxName}_tenantId`],
       clientId: process.env[`${cnxName}_clientId`] ?? (() => { throw new Error(`ClientId not found for connection: ${cnxName}`) })(),
@@ -97,10 +109,11 @@ export const loadAuthConfigFromEnv: (cnxName?: string) => AuthConfiguration = (c
       certKeyFile: process.env[`${cnxName}_certKeyFile`],
       connectionName: process.env[`${cnxName}_connectionName`],
       FICClientId: process.env[`${cnxName}_FICClientId`],
+      authority,
       issuers: [
         'https://api.botframework.com',
         `https://sts.windows.net/${process.env[`${cnxName}_tenantId`]}/`,
-        `https://login.microsoftonline.com/${process.env[`${cnxName}_tenantId`]}/v2.0`
+        `${authority}/${process.env[`${cnxName}_tenantId`]}/v2.0`
       ]
     }
   }
@@ -122,6 +135,7 @@ export const loadPrevAuthConfigFromEnv: () => AuthConfiguration = () => {
   if (process.env.MicrosoftAppId === undefined && process.env.NODE_ENV === 'production') {
     throw new Error('ClientId required in production')
   }
+  const authority = process.env.authorityEndpoint ?? 'https://login.microsoftonline.com'
   return {
     tenantId: process.env.MicrosoftAppTenantId,
     clientId: process.env.MicrosoftAppId!,
@@ -130,10 +144,11 @@ export const loadPrevAuthConfigFromEnv: () => AuthConfiguration = () => {
     certKeyFile: process.env.certKeyFile,
     connectionName: process.env.connectionName,
     FICClientId: process.env.MicrosoftAppClientId,
+    authority,
     issuers: [
       'https://api.botframework.com',
       `https://sts.windows.net/${process.env.MicrosoftAppTenantId}/`,
-      `https://login.microsoftonline.com/${process.env.MicrosoftAppTenantId}/v2.0`
+      `${authority}/${process.env.MicrosoftAppTenantId}/v2.0`
     ]
   }
 }

package/src/auth/jwt-middleware.ts

@@ -24,7 +24,7 @@ const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtP
     logger.debug('jwt.decode ', JSON.stringify(payload))
     const jwksUri: string = payload.iss === 'https://api.botframework.com'
       ? 'https://login.botframework.com/v1/.well-known/keys'
-      : `https://login.microsoftonline.com/${config.tenantId}/discovery/v2.0/keys`
+      : `${config.authority}/${config.tenantId}/discovery/v2.0/keys`
 
     logger.debug(`fetching keys from ${jwksUri}`)
     const jwksClient: JwksClient = jwksRsa({ jwksUri })

package/src/auth/msalTokenProvider.ts

@@ -55,7 +55,7 @@ export class MsalTokenProvider implements AuthProvider {
     const cca = new ConfidentialClientApplication({
       auth: {
         clientId: authConfig.clientId as string,
-        authority: `https://login.microsoftonline.com/${authConfig.tenantId || 'botframework.com'}`,
+        authority: `${authConfig.authority}/${authConfig.tenantId || 'botframework.com'}`,
         clientSecret: authConfig.clientSecret
       },
       system: this.sysOptions
@@ -137,7 +137,7 @@ export class MsalTokenProvider implements AuthProvider {
     const cca = new ConfidentialClientApplication({
       auth: {
         clientId: authConfig.clientId || '',
-        authority: `https://login.microsoftonline.com/${authConfig.tenantId || 'botframework.com'}`,
+        authority: `${authConfig.authority}/${authConfig.tenantId || 'botframework.com'}`,
         clientCertificate: {
           privateKey: privateKey as string,
           thumbprint: pubKeyObject.fingerprint.replaceAll(':', ''),
@@ -163,7 +163,7 @@ export class MsalTokenProvider implements AuthProvider {
     const cca = new ConfidentialClientApplication({
       auth: {
         clientId: authConfig.clientId as string,
-        authority: `https://login.microsoftonline.com/${authConfig.tenantId || 'botframework.com'}`,
+        authority: `${authConfig.authority}/${authConfig.tenantId || 'botframework.com'}`,
         clientSecret: authConfig.clientSecret
       },
       system: this.sysOptions
@@ -187,7 +187,7 @@ export class MsalTokenProvider implements AuthProvider {
     const cca = new ConfidentialClientApplication({
       auth: {
         clientId: authConfig.clientId as string,
-        authority: `https://login.microsoftonline.com/${authConfig.tenantId}`,
+        authority: `${authConfig.authority}/${authConfig.tenantId}`,
         clientAssertion
       },
       system: this.sysOptions

package/src/connector-client/connectorClient.ts

@@ -27,6 +27,20 @@ export class ConnectorClient {
    */
   protected constructor (axInstance: AxiosInstance) {
     this._axiosInstance = axInstance
+    this._axiosInstance.interceptors.request.use((config) => {
+      const { method, url, data, headers, params } = config
+      // Clone headers and remove Authorization before logging
+      const { Authorization, authorization, ...headersToLog } = headers || {}
+      logger.debug('Request: ', {
+        host: this._axiosInstance.getUri(),
+        url,
+        data,
+        method,
+        params,
+        headers: headersToLog
+      })
+      return config
+    })
     this._axiosInstance.interceptors.response.use(
       (config) => {
         const { status, statusText, config: requestConfig } = config

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.