@microsoft/agents-hosting 1.5.0-beta.1.g77c44097fe → 1.5.0-beta.12.ga9a2b23c19

package/src/app/agentApplication.ts

@@ -20,7 +20,10 @@ import { RouteList } from './routeList'
 import { TranscriptLoggerMiddleware } from '../transcript'
 import { CloudAdapter } from '../cloudAdapter'
 import { Authorization, UserAuthorization, AuthorizationManager } from './auth'
+import { Proactive } from './proactive'
 import { JwtPayload } from 'jsonwebtoken'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../errorHelper'
 
 const logger = debug('agents:app')
 
@@ -76,6 +79,7 @@ export class AgentApplication<TState extends TurnState> {
   private readonly _adapter?: CloudAdapter
   private readonly _authorizationManager?: AuthorizationManager
   private readonly _authorization?: Authorization
+  private readonly _proactive?: Proactive<TState>
   private _typingTimer: NodeJS.Timeout | undefined
   protected readonly _extensions: AgentExtension<TState>[] = []
   private readonly _adaptiveCards: AdaptiveCardsActions<TState>
@@ -130,6 +134,14 @@ export class AgentApplication<TState extends TurnState> {
       this._authorization = new UserAuthorization(this._authorizationManager)
     }
 
+    // Create Proactive whenever proactive options are explicitly configured or a storage
+    // backend is available — no explicit `proactive` option is required.
+    if (this._options.proactive !== undefined || this._options.storage !== undefined) {
+      const proactiveOpts = this._options.proactive ?? {}
+      const proactiveStorage = proactiveOpts.storage ?? this._options.storage
+      this._proactive = new Proactive<TState>(this, { ...proactiveOpts, storage: proactiveStorage })
+    }
+
     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.')
     }
@@ -157,6 +169,27 @@ export class AgentApplication<TState extends TurnState> {
     return this._authorization
   }
 
+  /**
+   * Gets the proactive messaging subsystem.
+   *
+   * @throws Error if no storage backend was configured (neither `options.storage` nor
+   *   `options.proactive.storage`).
+   */
+  public get proactive (): Proactive<TState> {
+    if (!this._proactive) {
+      throw ExceptionHelper.generateException(Error, Errors.ProactivePropertyUnavailable)
+    }
+    return this._proactive
+  }
+
+  /**
+   * Returns `true` if user authorization was configured, without throwing.
+   * Used internally by the Proactive subsystem to check whether token acquisition is available.
+   */
+  public get hasUserAuthorization (): boolean {
+    return this._authorization !== undefined
+  }
+
   /**
    * Gets the options used to configure the application.
    *
@@ -583,10 +616,10 @@ export class AgentApplication<TState extends TurnState> {
    * While this method is public, it's typically called internally by the `run` method.
    *
    * The method performs the following operations:
-   * 1. Starts typing timer if configured
-   * 2. Processes mentions if configured
-   * 3. Loads turn state
-   * 4. Handles authentication flows
+   * 1. Handles authentication flows for routes that have auth handlers configured. If NOT authorized, it will not continue with the 2nd step, returning false.
+   * 2. Starts typing timer if configured
+   * 3. Processes mentions if configured
+   * 4. Loads turn state
    * 5. Downloads files if file downloaders are configured
    * 6. Executes before-turn event handlers
    * 7. Routes to appropriate handlers
@@ -600,76 +633,98 @@ export class AgentApplication<TState extends TurnState> {
    *   console.log('No handler matched the activity');
    * }
    * ```
-   *
    */
   public async runInternal (turnContext: TurnContext): Promise<boolean> {
-    if (turnContext.activity.type === ActivityTypes.Typing) {
+    const { authorized, context } = await this.handleAuthorization(turnContext)
+
+    if (!authorized) {
+      // We don't log a message here because it is handled by the authorization manager and could cause confusion during mid sign-in operations.
       return false
     }
 
-    logger.info('Running application with activity:', turnContext.activity.id!)
-    return await this.startLongRunningCall(turnContext, async (context) => {
-      try {
-        if (this._options.startTypingTimer) {
-          this.startTypingTimer(context)
-        }
+    const isLongRunning =
+      (turnContext.activity.type === ActivityTypes.Invoke && turnContext.activity.name === 'signin/tokenExchange') ||
+      (this._options.longRunningMessages && turnContext.activity.type === ActivityTypes.Message)
 
-        if (this._options.removeRecipientMention && context.activity.type === ActivityTypes.Message) {
-          context.activity.removeRecipientMention()
-        }
+    if (isLongRunning) {
+      logger.debug('Starting long-running messages for activity:', context.activity.id!)
+      this.startLongRunningCall(context, ctx => this.runTurn(ctx))
+      return true
+    }
 
-        if (this._options.normalizeMentions && context.activity.type === ActivityTypes.Message) {
-          context.activity.normalizeMentions()
-        }
+    logger.info('Running application with activity:', context.activity.id!)
+    return this.runTurn(context)
+  }
 
-        const { storage, turnStateFactory } = this._options
-        const state = turnStateFactory()
-        await state.load(context, storage)
+  /**
+   * Determines if the incoming activity is authorized to be processed by the application.
+   * @returns An object containing the authorization status and the context (could have the continuation activity) to be used for further processing.
+   */
+  private async handleAuthorization (context: TurnContext) {
+    if (context.activity.type === ActivityTypes.Typing) {
+      return { authorized: true, context }
+    }
 
-        const { authorized } = await this._authorizationManager?.process(context, async activity => {
-          // The incoming activity may come from the storage, so we need to restore the auth handlers.
-          // Since the current route may not have auth handlers.
-          const route = await this.getRoute(new TurnContext(context.adapter, activity, turnContext.identity))
-          return route?.authHandlers ?? []
-        }) ?? { authorized: true } // Default to authorized if no auth manager
+    return this._authorizationManager?.process(context, async activity => {
+      // The incoming activity may come from the storage, so we need to restore the auth handlers.
+      // Since the current route may not have auth handlers.
+      const route = await this.getRoute(new TurnContext(context.adapter, activity, context.identity))
+      return route?.authHandlers ?? []
+    }) ?? { authorized: true, context } // If no authorization manager is configured, we assume the activity is authorized.
+  }
 
-        if (!authorized) {
-          await state.save(context, storage)
-          return false
-        }
+  /**
+   * Executes the turn processing logic for the given context, including routing and handler execution.
+   */
+  private async runTurn (context: TurnContext): Promise<boolean> {
+    try {
+      if (this._options.startTypingTimer) {
+        this.startTypingTimer(context)
+      }
 
-        const route = await this.getRoute(context)
+      if (this._options.removeRecipientMention && context.activity.type === ActivityTypes.Message) {
+        context.activity.removeRecipientMention()
+      }
 
-        if (!route) {
-          logger.debug('No matching route found for activity:', context.activity)
-          return false
-        }
+      if (this._options.normalizeMentions && context.activity.type === ActivityTypes.Message) {
+        context.activity.normalizeMentions()
+      }
 
-        if (Array.isArray(this._options.fileDownloaders) && this._options.fileDownloaders.length > 0) {
-          for (let i = 0; i < this._options.fileDownloaders.length; i++) {
-            await this._options.fileDownloaders[i].downloadAndStoreFiles(context, state)
-          }
-        }
+      const { storage, turnStateFactory } = this._options
+      const state = turnStateFactory()
+      await state.load(context, storage)
 
-        if (!(await this.callEventHandlers(context, state, this._beforeTurn))) {
-          await state.save(context, storage)
-          return false
-        }
+      const route = await this.getRoute(context)
 
-        await route.handler(context, state)
+      if (!route) {
+        logger.debug('No matching route found for activity:', context.activity)
+        return false
+      }
 
-        if (await this.callEventHandlers(context, state, this._afterTurn)) {
-          await state.save(context, storage)
+      if (Array.isArray(this._options.fileDownloaders) && this._options.fileDownloaders.length > 0) {
+        for (let i = 0; i < this._options.fileDownloaders.length; i++) {
+          await this._options.fileDownloaders[i].downloadAndStoreFiles(context, state)
         }
+      }
 
-        return true
-      } catch (err: any) {
-        logger.error(err)
-        throw err
-      } finally {
-        this.stopTypingTimer()
+      if (!(await this.callEventHandlers(context, state, this._beforeTurn))) {
+        await state.save(context, storage)
+        return false
       }
-    })
+
+      await route.handler(context, state)
+
+      if (await this.callEventHandlers(context, state, this._afterTurn)) {
+        await state.save(context, storage)
+      }
+
+      return true
+    } catch (err: any) {
+      logger.error(err)
+      throw err
+    } finally {
+      this.stopTypingTimer()
+    }
   }
 
   /**
@@ -900,35 +955,31 @@ export class AgentApplication<TState extends TurnState> {
   }
 
   /**
-   * Starts a long-running call, potentially in a new conversation context.
+   * Starts a long-running call by continuing the conversation asynchronously (fire-and-forget).
+   * The current request/response cycle is not blocked; errors are forwarded to the adapter's error handler.
    *
    * @param context - The turn context for the current conversation.
-   * @param handler - The handler function to execute.
-   * @returns A promise that resolves to the result of the handler.
+   * @param handler - The handler function to execute in the continued conversation.
    */
   protected startLongRunningCall (
     context: TurnContext,
-    handler: (context: TurnContext) => Promise<boolean>
-  ): Promise<boolean> {
-    if (context.activity.type === ActivityTypes.Message && this._options.longRunningMessages) {
-      return new Promise<boolean>((resolve, reject) => {
-        this.continueConversationAsync(context.identity, context, async (ctx) => {
-          try {
-            for (const key in context.activity) {
-              (ctx.activity as any)[key] = (context.activity as any)[key]
-            }
-
-            const result = await handler(ctx)
-            resolve(result)
-          } catch (err: any) {
-            logger.error(err)
-            reject(err)
-          }
-        })
-      })
-    } else {
-      return handler(context)
-    }
+    handler: (context: TurnContext) => Promise<any>
+  ) {
+    const activity = Activity.fromObject(context.activity)
+    this.continueConversationAsync(context.identity, activity.getConversationReference(), async (ctx) => {
+      try {
+        Object.assign(ctx.activity, activity)
+        await handler(ctx)
+      } catch (err) {
+        if (this.adapter.onTurnError && err instanceof Error) {
+          await this.adapter.onTurnError(ctx, err)
+        } else {
+          throw err
+        }
+      }
+    }).catch(err => {
+      logger.error(`Unhandled error in long-running call for activity '${activity.type}' (id: ${activity.id}):`, err)
+    })
   }
 
   /**

package/src/app/agentApplicationBuilder.ts

@@ -7,6 +7,7 @@ import { Storage } from '../storage'
 import { AgentApplication } from './agentApplication'
 import { AgentApplicationOptions } from './agentApplicationOptions'
 import { AuthorizationOptions } from './auth/types'
+import { ProactiveOptions } from './proactive'
 import { TurnState } from './turnState'
 
 /**
@@ -64,6 +65,16 @@ export class AgentApplicationBuilder<TState extends TurnState = TurnState> {
     return this
   }
 
+  /**
+   * Configures the proactive messaging subsystem.
+   * @param options Proactive options including optional storage backend
+   * @returns This builder instance for chaining
+   */
+  public withProactive (options: ProactiveOptions): this {
+    this._options.proactive = options
+    return this
+  }
+
   /**
    * Builds and returns a new AgentApplication instance configured with the provided options.
    * @returns A new AgentApplication instance

package/src/app/agentApplicationOptions.ts

@@ -12,6 +12,7 @@ import { TurnState } from './turnState'
 import { HeaderPropagationDefinition } from '../headerPropagation'
 import { AuthorizationOptions } from './auth/types'
 import { Connections } from '../auth/connections'
+import { ProactiveOptions } from './proactive'
 
 /**
  * Configuration options for creating and initializing an Agent Application.
@@ -147,4 +148,10 @@ export interface AgentApplicationOptions<TState extends TurnState> {
    * identity providers.
    */
   connections?: Connections
+
+  /**
+   * Optional. Configuration for the proactive messaging subsystem.
+   * When provided, `app.proactive` will be available.
+   */
+  proactive?: ProactiveOptions
 }

package/src/app/auth/authorizationManager.ts

@@ -29,6 +29,10 @@ interface AuthorizationManagerProcessResult {
    * Indicates whether the authorization was successful.
    */
   authorized: boolean;
+  /**
+   * The context associated with the authorization process.
+   */
+  context: TurnContext;
 }
 
 /**
@@ -111,13 +115,16 @@ export class AuthorizationManager {
     if (active !== undefined && active?.data.activity.conversation?.id !== context.activity.conversation?.id) {
       logger.warn('Discarding the active session due to the conversation has changed during an active sign-in process', active?.data.activity)
       await storage.delete()
-      return { authorized: true }
+      return { authorized: true, context }
     }
 
     const handlers = active?.handlers ?? this.mapHandlers(await getHandlerIds(context.activity) ?? []) ?? []
 
+    // Create a shallow copy to modify the activity, since the signin process depends on it and we want to ensure the next handler depends on the initial activity, not the modified one.
+    const sharedContext = new TurnContext(context)
+
     for (const handler of handlers) {
-      const status = await this.signin(storage, handler, context, active?.data)
+      const status = await this.signin(storage, handler, sharedContext, active?.data)
       logger.debug(this.prefix(handler.id, `Sign-in status: ${status}`))
 
       if (status === AuthorizationHandlerStatus.IGNORED) {
@@ -126,17 +133,17 @@ export class AuthorizationManager {
       }
 
       if (status === AuthorizationHandlerStatus.PENDING) {
-        return { authorized: false }
+        return { authorized: false, context: sharedContext }
       }
 
       if (status === AuthorizationHandlerStatus.REJECTED) {
         await storage.delete()
-        return { authorized: false }
+        return { authorized: false, context: sharedContext }
       }
 
       if (status === AuthorizationHandlerStatus.REVALIDATE) {
         await storage.delete()
-        return this.process(context, getHandlerIds)
+        return this.process(sharedContext, getHandlerIds)
       }
 
       if (status !== AuthorizationHandlerStatus.APPROVED) {
@@ -146,14 +153,12 @@ export class AuthorizationManager {
       await storage.delete()
 
       if (active) {
-        // Restore the original activity in the turn context for the next handler to process.
-        // This is done like this to avoid losing data that may be set in the turn context.
-        (context as any)._activity = Activity.fromObject(active.data.activity)
+        (sharedContext as any)._activity = Activity.fromObject(active.data.activity)
         active = undefined
       }
     }
 
-    return { authorized: true }
+    return { authorized: true, context: sharedContext }
   }
 
   /**

package/src/app/auth/handlers/azureBotAuthorization.ts

@@ -307,7 +307,8 @@ export class AzureBotAuthorization implements AuthorizationHandler {
       if (status !== AuthorizationHandlerStatus.IGNORED) {
         return status
       }
-    } else if (active.category === Category.SIGNIN) {
+    } else if (active.category === Category.SIGNIN && activity.channelId === Channels.Msteams) {
+      // Specific to MS Teams, M365 does not send signin/verifyState when user consent is required.
       // This is only for safety in case of unexpected behaviors during the MS Teams sign-in process,
       // e.g., user interrupts the flow by clicking the Consent Cancel button.
       logger.warn(this.prefix('The incoming activity will be revalidated due to a change in the sign-in flow'), activity)
@@ -550,8 +551,7 @@ export class AzureBotAuthorization implements AuthorizationHandler {
    * Sends an InvokeResponse activity if the channel is Microsoft Teams, including Copilot within MS Teams.
    */
   private sendInvokeResponse <T>(context: TurnContext, response: InvokeResponse<T>) {
-    const [parentChannel] = Activity.parseChannelId(context.activity.channelId!)
-    if (parentChannel !== Channels.Msteams) {
+    if (context.activity.channelIdChannel !== Channels.Msteams) {
       return Promise.resolve()
     }
 

package/src/app/index.ts

@@ -19,3 +19,4 @@ export * from './adaptiveCards'
 export * from './streaming/streamingResponse'
 export * from './streaming/citation'
 export * from './teamsAttachmentDownloader'
+export * from './proactive'

package/src/app/proactive/conversation.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import type { JwtPayload } from 'jsonwebtoken'
+import type { ConversationReference } from '@microsoft/agents-activity'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import type { TurnContext } from '../../turnContext'
+import { Errors } from '../../errorHelper'
+
+/**
+ * JWT-like claims identifying the agent for proactive authentication.
+ * `aud` (the agent's client ID) is required; all other fields are optional.
+ */
+export interface ConversationClaims {
+  aud: string
+  azp?: string
+  appid?: string
+  tid?: string
+  [key: string]: string | undefined
+}
+
+/**
+ * A serializable pair of a `ConversationReference` and the JWT claims needed
+ * to authenticate proactive calls on behalf of this agent.
+ *
+ * Instances are stored in and retrieved from the proactive storage backend.
+ * The `identity` getter produces the `JwtPayload` shape expected by
+ * `adapter.continueConversation()`.
+ */
+export class Conversation {
+  reference: ConversationReference
+  claims: ConversationClaims
+
+  constructor (context: TurnContext)
+  constructor (claims: ConversationClaims, reference: ConversationReference)
+  constructor (
+    contextOrClaims: TurnContext | ConversationClaims,
+    reference?: ConversationReference
+  ) {
+    if ('activity' in contextOrClaims) {
+      // TurnContext overload
+      const context = contextOrClaims as TurnContext
+      this.reference = context.activity.getConversationReference()
+      const id = context.identity as JwtPayload | undefined
+      this.claims = {
+        ...(id ?? {}),
+        aud: Array.isArray(id?.aud) ? (id.aud as string[])[0] : (id?.aud ?? '')
+      } as ConversationClaims
+    } else {
+      // (claims, reference) overload — matches C# parameter order
+      this.claims = contextOrClaims as ConversationClaims
+      this.reference = reference!
+    }
+  }
+
+  /**
+   * Returns a `JwtPayload`-compatible object for passing to
+   * `adapter.continueConversation()` as `botAppIdOrIdentity`.
+   */
+  get identity (): JwtPayload {
+    return this.claims as unknown as JwtPayload
+  }
+
+  /**
+   * Returns a JSON string of `{ reference, claims }` — suitable for use in
+   * HTTP request bodies when passing a conversation to another service.
+   */
+  toJson (): string {
+    return JSON.stringify({ reference: this.reference, claims: this.claims })
+  }
+
+  /**
+   * Throws if any required field is missing.
+   * Called by `Proactive.storeConversation()` before writing to storage.
+   */
+  validate (): void {
+    if (!this.reference.conversation?.id) {
+      throw ExceptionHelper.generateException(Error, Errors.ConversationInvalidId)
+    }
+    if (!this.reference.serviceUrl) {
+      throw ExceptionHelper.generateException(Error, Errors.ConversationInvalidServiceUrl)
+    }
+    if (!this.claims.aud) {
+      throw ExceptionHelper.generateException(Error, Errors.ConversationInvalidAud)
+    }
+  }
+}

package/src/app/proactive/conversationBuilder.ts

@@ -0,0 +1,139 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import type { ChannelAccount, ConversationAccount, ConversationReference } from '@microsoft/agents-activity'
+import type { TurnContext } from '../../turnContext'
+import { Conversation, type ConversationClaims } from './conversation'
+import { ConversationReferenceBuilder } from './conversationReferenceBuilder'
+
+/**
+ * Fluent builder for the `Conversation` class.
+ *
+ * @example
+ * ```typescript
+ * // Build from scratch
+ * const conv = ConversationBuilder
+ *   .create('my-client-id', 'msteams')
+ *   .withUser('user-aad-id')
+ *   .withConversationId('19:channel@thread.skype')
+ *   .build()
+ *
+ * // Build from a live TurnContext
+ * const conv = ConversationBuilder.fromContext(turnContext).build()
+ * ```
+ */
+export class ConversationBuilder {
+  private readonly _agentClientId: string
+  private readonly _channelId: string
+  private readonly _serviceUrl: string
+  private _claims: ConversationClaims
+  private _reference: Partial<ConversationReference>
+
+  private constructor (
+    agentClientId: string,
+    channelId: string,
+    serviceUrl: string,
+    claims: ConversationClaims,
+    reference: Partial<ConversationReference>
+  ) {
+    this._agentClientId = agentClientId
+    this._channelId = channelId
+    this._serviceUrl = serviceUrl
+    this._claims = claims
+    this._reference = reference
+  }
+
+  /**
+   * Creates a new builder for the given agent and channel.
+   * @param requestorId Optional: the client ID of the app making the request.
+   *   Becomes the `appid` claim, used in multi-tenant Azure Bot scenarios.
+   */
+  static create (
+    agentClientId: string,
+    channelId: string,
+    serviceUrl?: string,
+    requestorId?: string
+  ): ConversationBuilder {
+    const claims: ConversationClaims = { aud: agentClientId }
+    if (requestorId) claims.appid = requestorId
+    return new ConversationBuilder(agentClientId, channelId, serviceUrl ?? '', claims, ConversationReferenceBuilder.create(agentClientId, channelId, serviceUrl).build())
+  }
+
+  /**
+   * Creates a builder pre-populated from a live `TurnContext`.
+   * Captures both the conversation reference and the JWT identity claims.
+   */
+  static fromContext (context: TurnContext): ConversationBuilder {
+    const ref = context.activity.getConversationReference()
+    const id = context.identity
+    const aud = Array.isArray(id?.aud) ? id.aud[0] : (id?.aud ?? '')
+    const claims: ConversationClaims = {
+      ...(id ?? {}),
+      aud,
+    } as ConversationClaims
+    return new ConversationBuilder(
+      aud,
+      ref.channelId,
+      ref.serviceUrl ?? '',
+      claims,
+      ref
+    )
+  }
+
+  /** Sets `reference.user`. */
+  withUser (userId: string, userName?: string): this {
+    const user: ChannelAccount = { id: userId, name: userName }
+    this._reference = { ...this._reference, user }
+    return this
+  }
+
+  /** Sets `reference.conversation.id`. */
+  withConversationId (id: string): this {
+    const conversation: ConversationAccount = { ...(this._reference.conversation ?? { isGroup: false }), id }
+    this._reference = { ...this._reference, conversation }
+    return this
+  }
+
+  /** Sets `reference.conversation` from a full `ConversationAccount`. */
+  withConversation (account: ConversationAccount): this {
+    this._reference = { ...this._reference, conversation: account }
+    return this
+  }
+
+  /** Sets `reference.activityId`. */
+  withActivityId (activityId: string): this {
+    this._reference = { ...this._reference, activityId }
+    return this
+  }
+
+  /**
+   * Merges a partial `ConversationReference` into the current one.
+   * Useful for overlaying externally-provided reference data without losing
+   * fields set by earlier builder calls.
+   */
+  withReference (ref: Partial<ConversationReference>): this {
+    this._reference = { ...this._reference, ...ref }
+    return this
+  }
+
+  /** Builds the `Conversation`, auto-filling `serviceUrl` from channel defaults if needed. */
+  build (): Conversation {
+    const serviceUrl =
+      this._serviceUrl ||
+      this._reference.serviceUrl ||
+      ConversationReferenceBuilder.serviceUrlForChannel(this._channelId)
+
+    const reference: ConversationReference = {
+      conversation: this._reference.conversation ?? { id: '', isGroup: false },
+      agent: this._reference.agent ?? { id: this._agentClientId },
+      ...this._reference,
+      // Ensure channelId and serviceUrl always use our resolved values
+      channelId: this._channelId,
+      serviceUrl,
+    }
+
+    const conv = new Conversation(this._claims, reference)
+    conv.validate()
+    return conv
+  }
+}