@microsoft/agents-hosting 1.7.0-beta.1.g8bcd4f11a7 → 1.7.1

package/src/errorHelper.ts

@@ -196,6 +196,21 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'missing context.activity.channelId'
   },
 
+  MissingContextActivityRecipientId: {
+    code: -120221,
+    description: 'missing context.activity.recipient.id'
+  },
+
+  MissingContextActivityConversationId: {
+    code: -120222,
+    description: 'missing context.activity.conversation.id'
+  },
+
+  MissingContextActivityFromId: {
+    code: -120223,
+    description: 'missing context.activity.from.id'
+  },
+
   /**
      * Error thrown when both channelId and from.id are required for operation.
      */
@@ -213,7 +228,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
   },
 
   // ============================================================================
-  // Attachment Errors (-120250 to -120290)
+  // Attachment Errors (-120250 to -120291)
   // ============================================================================
 
   /**
@@ -273,7 +288,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
   },
 
   // ============================================================================
-  // Connection and Authentication Errors (-120300 to -120590)
+  // Connection and Authentication Errors (-120300 to -120599)
   // ============================================================================
 
   /**
@@ -281,7 +296,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
      */
   ConnectionNotFoundInEnvironment: {
     code: -120300,
-    description: 'Connection "{connectionName}" not found in environment.'
+    description: 'Connection "{connectionName}" not found in environment connections.'
   },
 
   /**
@@ -348,6 +363,51 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'Connection settings must be provided for this operation.'
   },
 
+  ConnectionSettingsRequiredForGetAccessTokenScope: {
+    code: -120381,
+    description: 'Connection settings must be provided to constructor when calling getAccessToken(scope)'
+  },
+
+  ConnectionSettingsRequiredForAcquireTokenOnBehalfOf: {
+    code: -120382,
+    description: 'Connection settings must be provided to constructor when calling acquireTokenOnBehalfOf(scopes, oboAssertion)'
+  },
+
+  FailedToAcquireTokenOnBehalfOf: {
+    code: -120383,
+    description: 'Failed to acquire token on behalf of user'
+  },
+
+  ConnectionSettingsRequiredForGetAgenticInstanceToken: {
+    code: -120384,
+    description: 'Connection settings must be provided when calling getAgenticInstanceToken'
+  },
+
+  FailedToAcquireInstanceTokenForAgentInstance: {
+    code: -120385,
+    description: 'Failed to acquire instance token for agent instance: {agentAppInstanceId}'
+  },
+
+  FailedToAcquireInstanceTokenForUserToken: {
+    code: -120386,
+    description: 'Failed to acquire instance token for user token: {agentAppInstanceId}'
+  },
+
+  ConnectionSettingsRequiredForGetAgenticApplicationToken: {
+    code: -120387,
+    description: 'Connection settings must be provided when calling getAgenticApplicationToken'
+  },
+
+  IdpmResourceAbsoluteUriRequired: {
+    code: -120388,
+    description: 'idpmResource must be a valid absolute URI'
+  },
+
+  FailedToAcquireTokenViaIdentityProxyManagerForAgentInstance: {
+    code: -120389,
+    description: 'Failed to acquire token via IdentityProxyManager for agent instance: {agentAppInstanceId}'
+  },
+
   /**
      * Error thrown when identity is required to get token provider.
      */
@@ -356,6 +416,31 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'Identity is required to get the token provider.'
   },
 
+  FailedToAcquireTokenUsingCertificate: {
+    code: -120395,
+    description: 'Failed to acquire token using certificate'
+  },
+
+  FailedToAcquireTokenUsingClientSecret: {
+    code: -120396,
+    description: 'Failed to acquire token using client secret'
+  },
+
+  FailedToAcquireTokenUsingFICClientAssertion: {
+    code: -120397,
+    description: 'Failed to acquire token using FIC client assertion'
+  },
+
+  FailedToAcquireTokenUsingWIDClientAssertion: {
+    code: -120398,
+    description: 'Failed to acquire token using WID client assertion'
+  },
+
+  FailedToAcquireExternalTokenForFICClientAssertion: {
+    code: -120399,
+    description: 'Failed to acquire external token for FIC client assertion'
+  },
+
   /**
      * Error thrown when audience and service URL are required for token provider.
      */
@@ -726,6 +811,11 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'Agent name contains invalid characters: {agentName}'
   },
 
+  ContinueConversationBotAppIdOrIdentityRequired: {
+    code: -120631,
+    description: 'continueConversation: botAppIdOrIdentity is required'
+  },
+
   /**
    * Error thrown when failed to post activity to agent.
    */
@@ -743,7 +833,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
   },
 
   // ============================================================================
-  // Storage and State Errors (-120700 to -120730)
+  // Storage and State Errors (-120700 to -120732)
   // ============================================================================
 
   /**
@@ -754,6 +844,22 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'Storage: error writing "{key}" due to eTag conflict.'
   },
 
+  /**
+     * Error thrown when keys are required for storage read operations.
+     */
+  StorageReadKeysRequired: {
+    code: -120701,
+    description: 'Keys are required when reading.'
+  },
+
+  /**
+     * Error thrown when changes are required for storage write operations.
+     */
+  StorageWriteChangesRequired: {
+    code: -120702,
+    description: 'Changes are required when writing.'
+  },
+
   /**
      * Error thrown when storage option is not available in app options.
      */
@@ -778,96 +884,18 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'Invalid state scope: {scope}'
   },
 
-  // ============================================================================
-  // Application Configuration Errors (-120850 to -120900)
-  // ============================================================================
-
-  /**
-     * Error thrown when longRunningMessages property is unavailable.
-     */
-  LongRunningMessagesPropertyUnavailable: {
-    code: -120850,
-    description: 'The Application.longRunningMessages property is unavailable because no adapter was configured in the app.'
-  },
-
-  /**
-     * Error thrown when transcriptLogger property is unavailable.
-     */
-  TranscriptLoggerPropertyUnavailable: {
-    code: -120860,
-    description: 'The Application.transcriptLogger property is unavailable because no adapter was configured in the app.'
-  },
-
-  /**
-     * Error thrown when TranscriptLoggerMiddleware requires a TranscriptLogger instance.
-     */
-  TranscriptLoggerInstanceRequired: {
-    code: -120870,
-    description: 'TranscriptLoggerMiddleware requires a TranscriptLogger instance.'
-  },
-
-  /**
-     * Error thrown when extension is already registered.
-     */
-  ExtensionAlreadyRegistered: {
-    code: -120880,
-    description: 'Extension already registered'
-  },
-
-  /**
-     * Error thrown when invalid plugin type is added to MiddlewareSet.
-     */
-  InvalidMiddlewarePluginType: {
-    code: -120890,
-    description: 'MiddlewareSet.use(): invalid plugin type being added.'
-  },
-
-  /**
-     * Error thrown when the stream has already ended.
-     */
-  StreamAlreadyEnded: {
-    code: -120900,
-    description: 'The stream has already ended.'
-  },
-
-  // ============================================================================
-  // Adaptive Cards Errors (-120950 to -120980)
-  // ============================================================================
-
-  /**
-     * Error thrown when unexpected AdaptiveCards.actionExecute() is triggered.
-     */
-  UnexpectedActionExecute: {
-    code: -120950,
-    description: 'Unexpected AdaptiveCards.actionExecute() triggered for activity type: {activityType}'
-  },
-
-  /**
-     * Error thrown when unexpected AdaptiveCards.actionSubmit() is triggered.
-     */
-  UnexpectedActionSubmit: {
-    code: -120960,
-    description: 'Unexpected AdaptiveCards.actionSubmit() triggered for activity type: {activityType}'
-  },
-
-  /**
-     * Error thrown when unexpected AdaptiveCards.search() is triggered.
-     */
-  UnexpectedSearchAction: {
-    code: -120970,
-    description: 'Unexpected AdaptiveCards.search() triggered for activity type: {activityType}'
+  InvalidStatePath: {
+    code: -120731,
+    description: 'Invalid state path: {path}'
   },
 
-  /**
-     * Error thrown when invalid action value is provided.
-     */
-  InvalidActionValue: {
-    code: -120980,
-    description: 'Invalid action value: {error}'
+  TurnStateMissingStateScope: {
+    code: -120732,
+    description: 'TurnState missing state scope named "{scope}".'
   },
 
   // ============================================================================
-  // Proactive Messaging Errors (-120740 to -120799)
+  // Proactive Messaging Errors (-120740 to -120753)
   // ============================================================================
 
   /**
@@ -983,6 +1011,133 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'CreateConversationOptionsBuilder: Teams channel conversations require an initial activity. Call withActivity() before build().'
   },
 
+  // ============================================================================
+  // Hosting / Web layer errors (-120800 to -120840)
+  // ============================================================================
+
+  /**
+   * Error thrown by CloudAdapter.process when the incoming request lacks a parsed body.
+   * Indicates the hosting layer (e.g. express.json() or Fastify's JSON parser) was not configured.
+   */
+  MissingRequestBody: {
+    code: -120800,
+    description: '`request.body` parameter required; ensure your hosting layer parses JSON request bodies before invoking the adapter (e.g., express.json() with Express or Fastify\'s built-in JSON parser).'
+  },
+
+  /**
+   * Error thrown by verifyToken when the provided JWT cannot be decoded.
+   */
+  InvalidJwtToken: {
+    code: -120810,
+    description: 'invalid token'
+  },
+
+  /**
+   * Error thrown by verifyToken when the token audience does not match any configured connection clientId.
+   */
+  JwtAudienceMismatch: {
+    code: -120820,
+    description: 'Audience mismatch'
+  },
+
+  // ============================================================================
+  // Application Configuration Errors (-120850 to -120902)
+  // ============================================================================
+
+  /**
+     * Error thrown when longRunningMessages property is unavailable.
+     */
+  LongRunningMessagesPropertyUnavailable: {
+    code: -120850,
+    description: 'The Application.longRunningMessages property is unavailable because no adapter was configured in the app.'
+  },
+
+  /**
+     * Error thrown when transcriptLogger property is unavailable.
+     */
+  TranscriptLoggerPropertyUnavailable: {
+    code: -120860,
+    description: 'The Application.transcriptLogger property is unavailable because no adapter was configured in the app.'
+  },
+
+  /**
+     * Error thrown when TranscriptLoggerMiddleware requires a TranscriptLogger instance.
+     */
+  TranscriptLoggerInstanceRequired: {
+    code: -120870,
+    description: 'TranscriptLoggerMiddleware requires a TranscriptLogger instance.'
+  },
+
+  /**
+     * Error thrown when extension is already registered.
+     */
+  ExtensionAlreadyRegistered: {
+    code: -120880,
+    description: 'Extension already registered'
+  },
+
+  /**
+     * Error thrown when invalid plugin type is added to MiddlewareSet.
+     */
+  InvalidMiddlewarePluginType: {
+    code: -120890,
+    description: 'MiddlewareSet.use(): invalid plugin type being added.'
+  },
+
+  /**
+     * Error thrown when the stream has already ended.
+     */
+  StreamAlreadyEnded: {
+    code: -120900,
+    description: 'The stream has already ended.'
+  },
+
+  ConversationUpdateHandlerMustBeFunction: {
+    code: -120901,
+    description: "ConversationUpdate 'handler' for {event} is {handlerType}. Type of 'handler' must be a function."
+  },
+
+  ContinueConversationAdapterRequired: {
+    code: -120902,
+    description: "You must configure the Application with an 'adapter' before calling Application.continueConversationAsync()"
+  },
+
+  // ============================================================================
+  // Adaptive Cards Errors (-120950 to -120980)
+  // ============================================================================
+
+  /**
+     * Error thrown when unexpected AdaptiveCards.actionExecute() is triggered.
+     */
+  UnexpectedActionExecute: {
+    code: -120950,
+    description: 'Unexpected AdaptiveCards.actionExecute() triggered for activity type: {activityType}'
+  },
+
+  /**
+     * Error thrown when unexpected AdaptiveCards.actionSubmit() is triggered.
+     */
+  UnexpectedActionSubmit: {
+    code: -120960,
+    description: 'Unexpected AdaptiveCards.actionSubmit() triggered for activity type: {activityType}'
+  },
+
+  /**
+     * Error thrown when unexpected AdaptiveCards.search() is triggered.
+     */
+  UnexpectedSearchAction: {
+    code: -120970,
+    description: 'Unexpected AdaptiveCards.search() triggered for activity type: {activityType}'
+  },
+
+  /**
+     * Error thrown when invalid action value is provided.
+     */
+  InvalidActionValue: {
+    code: -120980,
+    description: 'Invalid action value: {error}'
+  },
+
   // ============================================================================
   // General Errors (-120990)
   // ============================================================================

package/src/headerPropagation.ts

@@ -3,6 +3,9 @@
  * Licensed under the MIT License.
  */
 
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from './errorHelper'
+
 /**
  * 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.
@@ -24,7 +27,7 @@ export class HeaderPropagation implements HeaderPropagationCollection {
 
   constructor (headers: Record<string, string | string[] | undefined>) {
     if (!headers) {
-      throw new Error('Headers must be provided.')
+      throw ExceptionHelper.generateException(Error, Errors.HeadersRequired)
     }
 
     this._incomingRequests = this.normalizeHeaders(headers)

package/src/index.ts

@@ -22,6 +22,7 @@ export * from './baseAdapter'
 // test-only internals (e.g., the per-process warning dedup set) do not leak
 // into the package's public API.
 export { CloudAdapter, type CloudAdapterOptions } from './cloudAdapter'
+export * from './createCloudAdapter'
 export * from './middlewareSet'
 export * from './messageFactory'
 export * from './statusCodes'
@@ -29,6 +30,7 @@ export * from './turnContext'
 export * from './turnContextStateCollection'
 export * from './storage/storage'
 export * from './headerPropagation'
+export * from './interfaces'
 export * from './httpClient'
 
 export * from './agent-client'

package/src/interfaces/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export * from './webResponse'

package/src/interfaces/webResponse.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Framework-agnostic response surface used by the hosting layer.
+ *
+ * @remarks
+ * This interface describes the minimal subset of an HTTP response object that
+ * `CloudAdapter.process` and `authorizeJWT` need at runtime. Any framework whose
+ * response object structurally satisfies this shape is compatible — including
+ * Express's `Response`, and adapter classes such as `FastifyReplyAdapter` from
+ * `@microsoft/agents-hosting-fastify`.
+ *
+ * Keeping this contract in the core hosting package means the hosting layer no
+ * longer needs to import types from `express` at compile time.
+ */
+export interface WebResponse {
+  status (code: number): this
+  setHeader (name: string, value: string): this
+  send (body?: unknown): this
+  end (): this
+  headersSent: boolean
+  writableEnded: boolean
+}
+
+/**
+ * Framework-agnostic `next` callback used by middleware-style functions in the
+ * hosting layer (notably `authorizeJWT`). Mirrors the shape of Express's
+ * `NextFunction` so existing Express middleware continues to work unchanged.
+ */
+export type NextFunction = (err?: any) => void
+
+/**
+ * Minimal HTTP request shape used by framework-agnostic route handlers.
+ *
+ * @remarks
+ * Augments {@link WebRequestParamsCarrier} so handlers can read URL params
+ * (`req.params.conversationId`) without coupling to Express's `Request` type.
+ */
+export interface WebRequestParamsCarrier {
+  params?: Record<string, string | undefined>
+}

package/src/middlewareSet.ts

@@ -1,6 +1,8 @@
 /** * Copyright (c) Microsoft Corporation. All rights reserved. * Licensed under the MIT License. */
+import { ExceptionHelper } from '@microsoft/agents-activity'
 import { TurnContext } from './turnContext'
 import { debug } from '@microsoft/agents-telemetry'
+import { Errors } from './errorHelper'
 
 const logger = debug('agents:middleware')
 
@@ -52,7 +54,7 @@ export class MiddlewareSet implements Middleware {
           typeof plugin === 'function' ? plugin : async (context, next) => await plugin.onTurn(context, next)
         )
       } else {
-        throw new Error('MiddlewareSet.use(): invalid plugin type being added.')
+        throw ExceptionHelper.generateException(Error, Errors.InvalidMiddlewarePluginType)
       }
     })
     return this

package/src/oauth/userTokenClient.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT License.
 
 import { HttpClient, HttpError } from '../httpClient'
-import { Activity, ConversationReference } from '@microsoft/agents-activity'
+import { Activity, ConversationReference, ExceptionHelper } from '@microsoft/agents-activity'
 import { debug } from '@microsoft/agents-telemetry'
 import { normalizeTokenExchangeState } from '../activityWireCompat'
 import { AadResourceUrls, SignInResource, TokenExchangeRequest, TokenOrSinginResourceResponse, TokenResponse, TokenStatus } from './userTokenClient.types'
@@ -12,6 +12,7 @@ import { HeaderPropagation, HeaderPropagationCollection } from '../headerPropaga
 import { getTokenServiceEndpoint } from './customUserTokenAPI'
 import { trace } from '@microsoft/agents-telemetry'
 import { UserTokenClientTraceDefinitions } from '../observability'
+import { Errors } from '../errorHelper'
 
 const logger = debug('agents:user-token-client')
 
@@ -150,7 +151,7 @@ export class UserTokenClient {
       const response = await this.executeRequest('delete', '/api/usertoken/SignOut', undefined, { params })
       record({ userId, connectionName, channelId, httpStatusCode: response.status?.toString() })
       if (response.status !== 200) {
-        throw new Error('Failed to sign out')
+        throw ExceptionHelper.generateException(Error, Errors.FailedToSignOut)
       }
     })
   }

package/src/state/conversationState.ts

@@ -6,7 +6,8 @@
 import { AgentState } from './agentState'
 import { Storage } from '../storage/storage'
 import { TurnContext } from '../turnContext'
-import { Activity } from '@microsoft/agents-activity'
+import { Activity, ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../errorHelper'
 
 /**
  * Manages the state of a conversation.
@@ -30,11 +31,11 @@ export class ConversationState extends AgentState {
     const conversationId = activity && (activity.conversation != null) && activity.conversation.id ? activity.conversation.id : undefined
 
     if (!channelId) {
-      throw new Error('missing activity.channelId')
+      throw ExceptionHelper.generateException(Error, Errors.MissingActivityChannelId)
     }
 
     if (!conversationId) {
-      throw new Error('missing activity.conversation.id')
+      throw ExceptionHelper.generateException(Error, Errors.MissingActivityConversationId)
     }
 
     return `${channelId}/conversations/${conversationId}/${this.namespace}`

package/src/state/userState.ts

@@ -6,7 +6,8 @@
 import { AgentState } from './agentState'
 import { Storage } from '../storage/storage'
 import { TurnContext } from '../turnContext'
-import { Activity } from '@microsoft/agents-activity'
+import { Activity, ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../errorHelper'
 
 /**
  * Manages the state of a user.
@@ -31,11 +32,11 @@ export class UserState extends AgentState {
     const userId = activity && (activity.from != null) && activity.from.id ? activity.from.id : undefined
 
     if (!channelId) {
-      throw new Error('missing activity.channelId')
+      throw ExceptionHelper.generateException(Error, Errors.MissingActivityChannelId)
     }
 
     if (!userId) {
-      throw new Error('missing activity.from.id')
+      throw ExceptionHelper.generateException(Error, Errors.MissingActivityFromId)
     }
 
     return `${channelId}/users/${userId}/${this.namespace}`

package/src/storage/memoryStorage.ts

@@ -4,9 +4,11 @@
  */
 
 import { trace } from '@microsoft/agents-telemetry'
+import { ExceptionHelper } from '@microsoft/agents-activity'
 import { StorageTraceDefinitions } from '../observability'
 import { Storage, StoreItem } from './storage'
 import { debug } from '@microsoft/agents-telemetry'
+import { Errors } from '../errorHelper'
 
 const logger = debug('agents:memory-storage')
 
@@ -66,7 +68,7 @@ export class MemoryStorage implements Storage {
     return trace(StorageTraceDefinitions.read, async ({ record }) => {
       record({ keyCount: keys?.length })
       if (!keys || keys.length === 0) {
-        throw new ReferenceError('Keys are required when reading.')
+        throw ExceptionHelper.generateException(ReferenceError, Errors.StorageReadKeysRequired)
       }
 
       const data: StoreItem = {}
@@ -98,7 +100,7 @@ export class MemoryStorage implements Storage {
   async write (changes: StoreItem): Promise<void> {
     return trace(StorageTraceDefinitions.write, async ({ record }) => {
       if (!changes || changes.length === 0) {
-        throw new ReferenceError('Changes are required when writing.')
+        throw ExceptionHelper.generateException(ReferenceError, Errors.StorageWriteChangesRequired)
       }
       record({ keyCount: changes.length })
 
@@ -112,7 +114,7 @@ export class MemoryStorage implements Storage {
           if (newItem.eTag === oldItem.eTag) {
             this.saveItem(key, newItem)
           } else {
-            throw new Error(`Storage: error writing "${key}" due to eTag conflict.`)
+            throw ExceptionHelper.generateException(Error, Errors.StorageETagConflict, undefined, { key })
           }
         }
       }

package/src/transcript/consoleTranscriptLogger.ts

@@ -1,5 +1,6 @@
-import { Activity } from '@microsoft/agents-activity'
+import { Activity, ExceptionHelper } from '@microsoft/agents-activity'
 import { TranscriptLogger } from './transcriptLogger'
+import { Errors } from '../errorHelper'
 
 /**
  * A transcript logger that logs activities to the console.
@@ -12,7 +13,7 @@ export class ConsoleTranscriptLogger implements TranscriptLogger {
    */
   logActivity (activity: Activity): void | Promise<void> {
     if (!activity) {
-      throw new Error('Activity is required.')
+      throw ExceptionHelper.generateException(Error, Errors.ActivityRequired)
     }
 
     console.log('Activity Log:', activity)