@microsoft/agents-hosting 1.6.1 → 1.7.0-beta.10.g0c6864b626

package/src/agent-client/agentClient.ts

@@ -1,11 +1,12 @@
 import { AuthConfiguration, MsalTokenProvider } from '../auth'
-import { Activity, ConversationReference, RoleTypes } from '@microsoft/agents-activity'
+import { Activity, ConversationReference, ExceptionHelper, RoleTypes } from '@microsoft/agents-activity'
 import { randomUUID } from 'crypto'
 import { debug } from '@microsoft/agents-telemetry'
 import { ConversationState } from '../state'
 import { TurnContext } from '../turnContext'
 import { trace } from '@microsoft/agents-telemetry'
 import { AgentClientTraceDefinitions } from '../observability'
+import { Errors } from '../errorHelper'
 
 const logger = debug('agents:agent-client')
 
@@ -125,7 +126,7 @@ export class AgentClient {
 
       if (!response.ok) {
         await conversationDataAccessor.delete(context, { channelId: activityCopy.channelId!, conversationId: activityCopy.conversation!.id })
-        throw new Error(`Failed to post activity to agent: ${response.statusText}`)
+        throw ExceptionHelper.generateException(Error, Errors.FailedToPostActivityToAgent, undefined, { statusText: response.statusText })
       }
       return response.statusText
     })
@@ -150,10 +151,10 @@ export class AgentClient {
           serviceUrl: process.env[`${agentName}_serviceUrl`]!
         }
       } else {
-        throw new Error(`Missing agent client config for agent ${agentName}`)
+        throw ExceptionHelper.generateException(Error, Errors.MissingAgentClientConfig, undefined, { agentName })
       }
     } else {
-      throw new Error('Agent name is required')
+      throw ExceptionHelper.generateException(Error, Errors.AgentNameRequired)
     }
   }
 }

package/src/agent-client/agentResponseHandler.ts

@@ -1,17 +1,33 @@
-import { Activity, ActivityTypes, ConversationReference } from '@microsoft/agents-activity'
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
 import { ActivityHandler } from '../activityHandler'
 import { CloudAdapter } from '../cloudAdapter'
-import { Request, Response, Application } from 'express'
-import { TurnContext } from '../turnContext'
-import { randomUUID } from 'crypto'
-import { normalizeIncomingActivity } from '../activityWireCompat'
-import { debug } from '@microsoft/agents-telemetry'
 import { ConversationState } from '../state'
+import { WebRequestParamsCarrier, WebResponse } from '../interfaces/webResponse'
+import { Request } from '../auth/request'
+import { AGENT_RESPONSE_ROUTE_PATH, createAgentResponseHandler } from './createAgentResponseHandler'
 
-const logger = debug('agents:agent-client')
-
-interface ConversationReferenceState {
-  conversationReference: ConversationReference
+/**
+ * Minimal application surface needed by {@link configureResponseController} to
+ * register the agent-to-agent response POST route. Express's `Application`
+ * structurally satisfies this; frameworks that do not (e.g., Fastify) should
+ * call {@link createAgentResponseHandler} directly and register the route
+ * themselves rather than passing a synthetic `WebApp`.
+ *
+ * `WebApp` is a minimal structural shape rather than a richer, named
+ * route-registrar contract. It is exported so it has a stable name in the
+ * generated type declarations and API report (it appears in the exported
+ * {@link configureResponseController} signature). Any framework `app` whose
+ * `post(path, handler)` method structurally matches satisfies it.
+ */
+export interface WebApp {
+  post (
+    path: string,
+    handler: (req: any, res: any) => unknown | Promise<unknown>
+  ): unknown
 }
 
 /**
@@ -33,10 +49,10 @@ interface ConversationReferenceState {
  * - Processing EndOfConversation activities by cleaning up conversation state
  * - Sending activities through the turn context and returning responses
  *
- * @param app - The Express application instance to configure the route on
- * @param adapter - The CloudAdapter instance used for processing bot framework activities and managing conversations
- * @param agent - The ActivityHandler instance that contains the bot's logic for processing different types of activities
- * @param conversationState - The ConversationState instance used for managing conversation-specific state and conversation references
+ * @param app - The application instance (Express `Application` or any framework that satisfies {@link WebApp}) to configure the route on.
+ * @param adapter - The CloudAdapter instance used for processing bot framework activities and managing conversations.
+ * @param agent - The ActivityHandler instance that contains the bot's logic for processing different types of activities.
+ * @param conversationState - The ConversationState instance used for managing conversation-specific state and conversation references.
  *
  * @example
  * ```typescript
@@ -48,57 +64,17 @@ interface ConversationReferenceState {
  * configureResponseController(app, adapter, agent, conversationState);
  * ```
  */
-export const configureResponseController = (app: Application, adapter: CloudAdapter, agent: ActivityHandler, conversationState: ConversationState) => {
-  app.post('/api/agentresponse/v3/conversations/:conversationId/activities/:activityId', handleResponse(adapter, agent, conversationState))
-}
-
-const handleResponse = (adapter: CloudAdapter, handler: ActivityHandler, conversationState: ConversationState) => async (req: Request, res: Response) => {
-  const incoming = normalizeIncomingActivity(req.body!)
-  const activity = Activity.fromObject(incoming)
-
-  logger.debug('received response: ', activity)
-
-  const connection = adapter.connectionManager.getDefaultConnection()
-  const appId = connection?.connectionSettings?.clientId ?? ''
-
-  const myTurnContext = new TurnContext(adapter, activity, CloudAdapter.createIdentity(appId))
-  const conversationDataAccessor = conversationState.createProperty<ConversationReferenceState>(req.params!.conversationId as string)
-  const conversationRefState = await conversationDataAccessor.get(myTurnContext, undefined, { channelId: activity.channelId!, conversationId: req.params!.conversationId as string })
-
-  const conversationRef = JSON.stringify(conversationRefState.conversationReference)
-  console.log('conversationRef', conversationRef)
-  const callback = async (turnContext: TurnContext) => {
-    activity.applyConversationReference(conversationRefState.conversationReference)
-    turnContext.activity.id = req.params!.activityId as string
-
-    let response
-    if (activity.type === ActivityTypes.EndOfConversation) {
-      await conversationDataAccessor.delete(turnContext, { channelId: activity.channelId!, conversationId: activity.conversation!.id })
-
-      applyActivityToTurnContext(turnContext, activity)
-      await handler.run(turnContext)
-
-      response = randomUUID().replace(/-/g, '')
-    } else {
-      response = await turnContext.sendActivity(activity)
-    }
-    res.status(200).send(response)
-  }
-
-  await adapter.continueConversation(myTurnContext.identity, conversationRefState.conversationReference, callback)
-}
-
-const applyActivityToTurnContext = (turnContext : TurnContext, activity : Activity) => {
-  turnContext.activity.channelData = activity.channelData
-  turnContext.activity.code = activity.code
-  turnContext.activity.entities = activity.entities
-  turnContext.activity.locale = activity.locale
-  turnContext.activity.localTimestamp = activity.localTimestamp
-  turnContext.activity.name = activity.name
-  turnContext.activity.relatesTo = activity.relatesTo
-  turnContext.activity.replyToId = activity.replyToId
-  turnContext.activity.timestamp = activity.timestamp
-  turnContext.activity.text = activity.text
-  turnContext.activity.type = activity.type
-  turnContext.activity.value = activity.value
+export const configureResponseController = (
+  app: WebApp,
+  adapter: CloudAdapter,
+  agent: ActivityHandler,
+  conversationState: ConversationState
+) => {
+  const handler = createAgentResponseHandler(adapter, agent, conversationState)
+  app.post(AGENT_RESPONSE_ROUTE_PATH, async (req: Request & WebRequestParamsCarrier, res: WebResponse) => {
+    await handler(req, res, {
+      conversationId: req.params!.conversationId as string,
+      activityId: req.params!.activityId as string
+    })
+  })
 }

package/src/agent-client/createAgentResponseHandler.ts

@@ -0,0 +1,133 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Activity, ActivityTypes, ConversationReference, ExceptionHelper } from '@microsoft/agents-activity'
+import { ActivityHandler } from '../activityHandler'
+import { CloudAdapter } from '../cloudAdapter'
+import { Request } from '../auth/request'
+import { WebResponse } from '../interfaces/webResponse'
+import { TurnContext } from '../turnContext'
+import { randomUUID } from 'crypto'
+import { normalizeIncomingActivity } from '../activityWireCompat'
+import { Errors } from '../errorHelper'
+import { debug } from '@microsoft/agents-telemetry'
+import { ConversationState } from '../state'
+
+const logger = debug('agents:agent-client')
+
+interface ConversationReferenceState {
+  conversationReference: ConversationReference
+}
+
+/**
+ * Route parameters supplied to {@link AgentResponseHandler} — typically pulled from
+ * the framework's URL path parser.
+ */
+export interface AgentResponseHandlerParams {
+  conversationId: string
+  activityId: string
+}
+
+/**
+ * Framework-agnostic handler signature for the agent response controller endpoint.
+ *
+ * @remarks
+ * The handler is intended to be invoked by a thin framework-specific wrapper (such
+ * as Express's `configureResponseController(app, ...)`) that extracts the path
+ * parameters and forwards a parsed `req.body` plus an {@link WebResponse}.
+ */
+export type AgentResponseHandler = (
+  req: Request,
+  res: WebResponse,
+  params: AgentResponseHandlerParams
+) => Promise<void>
+
+/**
+ * Creates a framework-agnostic handler for the agent response controller endpoint.
+ *
+ * This is the core, Express-free implementation used by:
+ * - `configureResponseController` in `@microsoft/agents-hosting-express`
+ * - `configureResponseController` in `@microsoft/agents-hosting-fastify`
+ *
+ * Both wrappers register the canonical route
+ * `POST /api/agentresponse/v3/conversations/:conversationId/activities/:activityId`
+ * and forward the parsed body + path parameters to the handler returned here.
+ *
+ * @param adapter - The CloudAdapter used for processing activities and managing conversations.
+ * @param agent - The ActivityHandler containing the agent logic.
+ * @param conversationState - The ConversationState used to look up the stored conversation reference.
+ * @returns A handler `(req, res, params) => Promise<void>`.
+ */
+export const createAgentResponseHandler = (
+  adapter: CloudAdapter,
+  agent: ActivityHandler,
+  conversationState: ConversationState
+): AgentResponseHandler => {
+  return async (req: Request, res: WebResponse, params: AgentResponseHandlerParams) => {
+    if (!req.body) {
+      throw ExceptionHelper.generateException(TypeError, Errors.MissingRequestBody)
+    }
+    const incoming = normalizeIncomingActivity(req.body)
+    const activity = Activity.fromObject(incoming)
+
+    logger.debug('received response: ', activity)
+
+    const connection = adapter.connectionManager.getDefaultConnection()
+    const appId = connection?.connectionSettings?.clientId ?? ''
+
+    const myTurnContext = new TurnContext(adapter, activity, CloudAdapter.createIdentity(appId))
+    const conversationDataAccessor = conversationState.createProperty<ConversationReferenceState>(params.conversationId)
+    const conversationRefState = await conversationDataAccessor.get(myTurnContext, undefined, { channelId: activity.channelId!, conversationId: params.conversationId })
+
+    const callback = async (turnContext: TurnContext) => {
+      activity.applyConversationReference(conversationRefState.conversationReference)
+      turnContext.activity.id = params.activityId
+
+      let response: unknown
+      let responseContentType: string | undefined
+      if (activity.type === ActivityTypes.EndOfConversation) {
+        await conversationDataAccessor.delete(turnContext, { channelId: activity.channelId!, conversationId: activity.conversation!.id })
+
+        applyActivityToTurnContext(turnContext, activity)
+        await agent.run(turnContext)
+
+        response = randomUUID().replace(/-/g, '')
+        // Explicitly set the content-type so Express and Fastify both emit the same
+        // value for this raw-string body (Express defaults to text/html, Fastify to
+        // text/plain when the framework auto-detects).
+        responseContentType = 'text/plain; charset=utf-8'
+      } else {
+        response = await turnContext.sendActivity(activity)
+      }
+      if (responseContentType !== undefined) {
+        res.setHeader('content-type', responseContentType)
+      }
+      res.status(200).send(response)
+    }
+
+    await adapter.continueConversation(myTurnContext.identity, conversationRefState.conversationReference, callback)
+  }
+}
+
+const applyActivityToTurnContext = (turnContext: TurnContext, activity: Activity) => {
+  turnContext.activity.channelData = activity.channelData
+  turnContext.activity.code = activity.code
+  turnContext.activity.entities = activity.entities
+  turnContext.activity.locale = activity.locale
+  turnContext.activity.localTimestamp = activity.localTimestamp
+  turnContext.activity.name = activity.name
+  turnContext.activity.relatesTo = activity.relatesTo
+  turnContext.activity.replyToId = activity.replyToId
+  turnContext.activity.timestamp = activity.timestamp
+  turnContext.activity.text = activity.text
+  turnContext.activity.type = activity.type
+  turnContext.activity.value = activity.value
+}
+
+/**
+ * Canonical route path for the agent response controller endpoint.
+ * Both Express and Fastify wrappers should register on this path.
+ */
+export const AGENT_RESPONSE_ROUTE_PATH = '/api/agentresponse/v3/conversations/:conversationId/activities/:activityId'

package/src/agent-client/index.ts

@@ -1,2 +1,3 @@
 export * from './agentClient'
 export * from './agentResponseHandler'
+export * from './createAgentResponseHandler'

package/src/app/adaptiveCards/activityValueParsers.ts

@@ -4,9 +4,9 @@
  */
 
 import { z } from 'zod'
-import { activityZodSchema, AdaptiveCardInvokeAction, adaptiveCardInvokeActionZodSchema } from '@microsoft/agents-activity'
-// import { MessagingExtensionQuery, messagingExtensionQueryZodSchema } from '../messageExtension/messagingExtensionQuery'
+import { activityZodSchema, AdaptiveCardInvokeAction, adaptiveCardInvokeActionZodSchema, ExceptionHelper } from '@microsoft/agents-activity'
 import { adaptiveCardsSearchParamsZodSchema } from './adaptiveCardsSearchParams'
+import { Errors } from '../../errorHelper'
 
 /**
  * Parses the given value as a value action.
@@ -76,7 +76,7 @@ export function parseValueActionExecuteSelector (value: unknown): ValueAction |
   })
   const safeParsedValue = actionValueExecuteSelector.passthrough().safeParse(value)
   if (!safeParsedValue.success) {
-    throw new Error(`Invalid action value: ${safeParsedValue.error}`)
+    throw ExceptionHelper.generateException(Error, Errors.InvalidActionValue, undefined, { error: String(safeParsedValue.error) })
   }
   const parsedValue = safeParsedValue.data
   return {

package/src/app/adaptiveCards/adaptiveCardsActions.ts

@@ -3,13 +3,14 @@
  * Licensed under the MIT License.
  */
 
-import { Activity, ActivityTypes } from '@microsoft/agents-activity'
+import { Activity, ActivityTypes, ExceptionHelper } from '@microsoft/agents-activity'
 import { AdaptiveCardInvokeResponse, AgentApplication, CardFactory, INVOKE_RESPONSE_KEY, InvokeResponse, MessageFactory, RouteSelector, TurnContext, TurnState } from '../../'
 import { AdaptiveCardActionExecuteResponseType } from './adaptiveCardActionExecuteResponseType'
 import { parseAdaptiveCardInvokeAction, parseValueActionExecuteSelector, parseValueDataset, parseValueSearchQuery } from './activityValueParsers'
 import { AdaptiveCardsSearchParams } from './adaptiveCardsSearchParams'
 import { AdaptiveCard } from '../../cards/adaptiveCard'
 import { Query } from './query'
+import { Errors } from '../../errorHelper'
 
 export const ACTION_INVOKE_NAME = 'adaptiveCard/action'
 const ACTION_EXECUTE_TYPE = 'Action.Execute'
@@ -117,8 +118,7 @@ export class AdaptiveCardsActions<TState extends TurnState> {
                         a?.name !== ACTION_INVOKE_NAME ||
                         (invokeAction?.action.type !== ACTION_EXECUTE_TYPE)
           ) {
-            throw new Error(`Unexpected AdaptiveCards.actionExecute() triggered for activity type: ${invokeAction?.action.type}`
-            )
+            throw ExceptionHelper.generateException(Error, Errors.UnexpectedActionExecute, undefined, { activityType: invokeAction?.action.type ?? 'undefined' })
           }
 
           if (invokeAction.action.verb !== v) {
@@ -196,7 +196,7 @@ export class AdaptiveCardsActions<TState extends TurnState> {
       this._app.addRoute(selector, async (context, state) => {
         const a = context?.activity
         if (a?.type !== ActivityTypes.Message || a?.text || typeof a?.value !== 'object') {
-          throw new Error(`Unexpected AdaptiveCards.actionSubmit() triggered for activity type: ${a?.type}`)
+          throw ExceptionHelper.generateException(Error, Errors.UnexpectedActionSubmit, undefined, { activityType: a?.type ?? 'undefined' })
         }
 
         await handler(context, state as TState, (parseAdaptiveCardInvokeAction(a.value)) as TData ?? {} as TData)
@@ -227,7 +227,7 @@ export class AdaptiveCardsActions<TState extends TurnState> {
         async (context, state) => {
           const a = context?.activity
           if (a?.type !== 'invoke' || a?.name !== SEARCH_INVOKE_NAME) {
-            throw new Error(`Unexpected AdaptiveCards.search() triggered for activity type: ${a?.type}`)
+            throw ExceptionHelper.generateException(Error, Errors.UnexpectedSearchAction, undefined, { activityType: a?.type ?? 'undefined' })
           }
 
           const parsedQuery = parseValueSearchQuery(a.value)

package/src/app/agentApplication.ts

@@ -87,6 +87,12 @@ export type ApplicationEventHandler<TState extends TurnState> = (context: TurnCo
  *
  */
 export class AgentApplication<TState extends TurnState> {
+  /** Turn-state key for the user authorization service configured on this application. */
+  public static readonly UserAuthorizationKey = Symbol('UserAuthorization')
+
+  /** Turn-state key for the token connections configured on this application. */
+  public static readonly ConnectionsKey = Symbol('Connections')
+
   protected readonly _options: AgentApplicationOptions<TState>
   protected readonly _routes: RouteList<TState> = new RouteList<TState>()
   protected readonly _beforeTurn: ApplicationEventHandler<TState>[] = []
@@ -155,12 +161,12 @@ export class AgentApplication<TState extends TurnState> {
     }
 
     if (this._options.longRunningMessages && !this._adapter && !this._options.agentAppId) {
-      throw new Error('The Application.longRunningMessages property is unavailable because no adapter was configured in the app.')
+      throw ExceptionHelper.generateException(Error, Errors.LongRunningMessagesPropertyUnavailable)
     }
 
     if (this._options.transcriptLogger) {
       if (!this._options.adapter) {
-        throw new Error('The Application.transcriptLogger property is unavailable because no adapter was configured in the app.')
+        throw ExceptionHelper.generateException(Error, Errors.TranscriptLoggerPropertyUnavailable)
       } else {
         this._adapter?.use(new TranscriptLoggerMiddleware(this._options.transcriptLogger))
       }
@@ -205,7 +211,7 @@ export class AgentApplication<TState extends TurnState> {
    */
   public get authorization (): Authorization {
     if (this._authorizationManager.handlers.length === 0) {
-      throw new Error('The Application.authorization property is unavailable because no authorization options were configured.')
+      throw ExceptionHelper.generateException(Error, Errors.AuthorizationOptionNotAvailable)
     }
     return this._authorization
   }
@@ -400,9 +406,7 @@ export class AgentApplication<TState extends TurnState> {
     isAgenticRoute: boolean = false
   ): this {
     if (typeof handler !== 'function') {
-      throw new Error(
-                `ConversationUpdate 'handler' for ${event} is ${typeof handler}. Type of 'handler' must be a function.`
-      )
+      throw ExceptionHelper.generateException(Error, Errors.ConversationUpdateHandlerMustBeFunction, undefined, { event, handlerType: typeof handler })
     }
 
     const selector = this.createConversationUpdateSelector(event, isAgenticRoute)
@@ -424,9 +428,7 @@ export class AgentApplication<TState extends TurnState> {
     logic: (context: TurnContext) => Promise<void>
   ): Promise<void> {
     if (!this._adapter) {
-      throw new Error(
-        "You must configure the Application with an 'adapter' before calling Application.continueConversationAsync()"
-      )
+      throw ExceptionHelper.generateException(Error, Errors.ContinueConversationAdapterRequired)
     }
 
     if (!this.options.agentAppId) {
@@ -510,9 +512,7 @@ export class AgentApplication<TState extends TurnState> {
     if (this.options.authorization) {
       this.authorization.onSignInSuccess(handler)
     } else {
-      throw new Error(
-        'The Application.authorization property is unavailable because no authorization options were configured.'
-      )
+      throw ExceptionHelper.generateException(Error, Errors.AuthorizationOptionNotAvailable)
     }
     return this
   }
@@ -540,9 +540,7 @@ export class AgentApplication<TState extends TurnState> {
     if (this.options.authorization) {
       this.authorization.onSignInFailure(handler)
     } else {
-      throw new Error(
-        'The Application.authorization property is unavailable because no authorization options were configured.'
-      )
+      throw ExceptionHelper.generateException(Error, Errors.AuthorizationOptionNotAvailable)
     }
     return this
   }
@@ -725,6 +723,15 @@ export class AgentApplication<TState extends TurnState> {
       record({ authorized: true, activity: context.activity })
 
       try {
+        if (this._authorizationManager.handlers.length > 0) {
+          context.turnState.set(AgentApplication.UserAuthorizationKey, this._authorization)
+        }
+
+        const connections = this._options.connections ?? this._adapter?.connectionManager
+        if (connections) {
+          context.turnState.set(AgentApplication.ConnectionsKey, connections)
+        }
+
         if (this._options.startTypingTimer) {
           this.startTypingTimer(context)
         }
@@ -965,7 +972,7 @@ export class AgentApplication<TState extends TurnState> {
    */
   public registerExtension<T extends AgentExtension<TState>> (extension: T, regcb : (ext:T) => void): void {
     if (this._extensions.includes(extension)) {
-      throw new Error('Extension already registered')
+      throw ExceptionHelper.generateException(Error, Errors.ExtensionAlreadyRegistered)
     }
     this._extensions.push(extension)
     regcb(extension)

package/src/app/streaming/streamingResponse.ts

@@ -3,11 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import { Activity, addAIToActivity, Attachment, Entity, ClientCitation, SensitivityUsageInfo, DeliveryModes, Channels } from '@microsoft/agents-activity'
+import { Activity, addAIToActivity, Attachment, Entity, ClientCitation, SensitivityUsageInfo, DeliveryModes, Channels, ExceptionHelper } from '@microsoft/agents-activity'
 import { TurnContext } from '../../turnContext'
 import { Citation } from './citation'
 import { CitationUtil } from './citationUtil'
 import { debug } from '@microsoft/agents-telemetry'
+import { Errors } from '../../errorHelper'
 
 const logger = debug('agents:streamingResponse')
 
@@ -137,7 +138,7 @@ export class StreamingResponse {
     }
 
     if (this._ended) {
-      throw new Error('The stream has already ended.')
+      throw ExceptionHelper.generateException(Error, Errors.StreamAlreadyEnded)
     }
 
     // Queue a typing activity
@@ -169,7 +170,7 @@ export class StreamingResponse {
     }
 
     if (this._ended) {
-      throw new Error('The stream has already ended.')
+      throw ExceptionHelper.generateException(Error, Errors.StreamAlreadyEnded)
     }
 
     // Update full message text
@@ -232,6 +233,7 @@ export class StreamingResponse {
     this._message = ''
     this._nextSequence = 1
     this._streamId = undefined
+    this._attachments = undefined
   }
 
   /**
@@ -250,6 +252,27 @@ export class StreamingResponse {
     this._attachments = attachments
   }
 
+  /**
+   * Adds an attachment to the collection of attachments for the final message.
+   *
+   * @param attachment The attachment to add. Must not be null or undefined.
+   * @throws Error if attachment is null or undefined.
+   *
+   * @remarks
+   * Attachments are only included in the final message sent by `endStream()`.
+   * They are not sent in intermediate typing activities.
+   */
+  public addAttachment (attachment: Attachment): void {
+    if (attachment === null || attachment === undefined) {
+      throw ExceptionHelper.generateException(Error, Errors.AttachmentNullOrUndefined)
+    }
+
+    if (!this._attachments) {
+      this._attachments = []
+    }
+    this._attachments.push(attachment)
+  }
+
   /**
    * Sets the sensitivity label to attach to the final chunk.
    *

package/src/app/turnState.ts

@@ -8,6 +8,8 @@ import { AppMemory } from './appMemory'
 import { TurnStateEntry } from './turnStateEntry'
 import { TurnContext } from '../turnContext'
 import { debug } from '@microsoft/agents-telemetry'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../errorHelper'
 
 const logger = debug('agents:turnState')
 
@@ -73,7 +75,6 @@ export class TurnState<
   private _scopes: Record<string, TurnStateEntry> = {}
   private _isLoaded = false
   private _loadingPromise?: Promise<boolean>
-  private _stateNotLoadedString = 'TurnState hasn\'t been loaded. Call load() first.'
 
   /**
    * Gets the conversation-scoped state.
@@ -87,7 +88,7 @@ export class TurnState<
   public get conversation (): TConversationState {
     const scope = this.getScope(CONVERSATION_SCOPE)
     if (!scope) {
-      throw new Error(this._stateNotLoadedString)
+      throw ExceptionHelper.generateException(Error, Errors.StateNotLoaded)
     }
     return scope.value as TConversationState
   }
@@ -101,7 +102,7 @@ export class TurnState<
   public set conversation (value: TConversationState) {
     const scope = this.getScope(CONVERSATION_SCOPE)
     if (!scope) {
-      throw new Error(this._stateNotLoadedString)
+      throw ExceptionHelper.generateException(Error, Errors.StateNotLoaded)
     }
     scope.replace(value as Record<string, unknown>)
   }
@@ -127,7 +128,7 @@ export class TurnState<
   public get user (): TUserState {
     const scope = this.getScope(USER_SCOPE)
     if (!scope) {
-      throw new Error(this._stateNotLoadedString)
+      throw ExceptionHelper.generateException(Error, Errors.StateNotLoaded)
     }
     return scope.value as TUserState
   }
@@ -141,7 +142,7 @@ export class TurnState<
   public set user (value: TUserState) {
     const scope = this.getScope(USER_SCOPE)
     if (!scope) {
-      throw new Error(this._stateNotLoadedString)
+      throw ExceptionHelper.generateException(Error, Errors.StateNotLoaded)
     }
     scope.replace(value as Record<string, unknown>)
   }
@@ -157,7 +158,7 @@ export class TurnState<
   public deleteConversationState (): void {
     const scope = this.getScope(CONVERSATION_SCOPE)
     if (!scope) {
-      throw new Error(this._stateNotLoadedString)
+      throw ExceptionHelper.generateException(Error, Errors.StateNotLoaded)
     }
     scope.delete()
   }
@@ -173,7 +174,7 @@ export class TurnState<
   public deleteUserState (): void {
     const scope = this.getScope(USER_SCOPE)
     if (!scope) {
-      throw new Error(this._stateNotLoadedString)
+      throw ExceptionHelper.generateException(Error, Errors.StateNotLoaded)
     }
     scope.delete()
   }
@@ -316,7 +317,7 @@ export class TurnState<
     }
 
     if (!this._isLoaded) {
-      throw new Error(this._stateNotLoadedString)
+      throw ExceptionHelper.generateException(Error, Errors.StateNotLoaded)
     }
 
     let changes: StoreItems | undefined
@@ -378,19 +379,19 @@ export class TurnState<
     const userId = activity?.from?.id
 
     if (!channelId) {
-      throw new Error('missing context.activity.channelId')
+      throw ExceptionHelper.generateException(Error, Errors.MissingContextActivityChannelId)
     }
 
     if (!agentId) {
-      throw new Error('missing context.activity.recipient.id')
+      throw ExceptionHelper.generateException(Error, Errors.MissingContextActivityRecipientId)
     }
 
     if (!conversationId) {
-      throw new Error('missing context.activity.conversation.id')
+      throw ExceptionHelper.generateException(Error, Errors.MissingContextActivityConversationId)
     }
 
     if (!userId) {
-      throw new Error('missing context.activity.from.id')
+      throw ExceptionHelper.generateException(Error, Errors.MissingContextActivityFromId)
     }
 
     const keys: Record<string, string> = {}
@@ -413,14 +414,14 @@ export class TurnState<
   private getScopeAndName (path: string): { scope: TurnStateEntry; name: string } {
     const parts = path.split('.')
     if (parts.length > 2) {
-      throw new Error(`Invalid state path: ${path}`)
+      throw ExceptionHelper.generateException(Error, Errors.InvalidStatePath, undefined, { path })
     } else if (parts.length === 1) {
       parts.unshift(TEMP_SCOPE)
     }
 
     const scope = this.getScope(parts[0])
     if (scope === undefined) {
-      throw new Error(`Invalid state scope: ${parts[0]}`)
+      throw ExceptionHelper.generateException(Error, Errors.InvalidStateScope, undefined, { scope: parts[0] })
     }
     return { scope, name: parts[1] }
   }