@microsoft/agents-hosting 1.5.0-beta.5.g18f3420031 → 1.5.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@microsoft/agents-hosting",
-  "version": "1.5.0-beta.5.g18f3420031",
+  "version": "1.5.1",
   "homepage": "https://github.com/microsoft/Agents-for-js",
   "repository": {
     "type": "git",
@@ -19,13 +19,14 @@
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "dependencies": {
-    "@azure/core-auth": "^1.10.1",
-    "@azure/msal-node": "^5.0.6",
-    "@microsoft/agents-activity": "1.5.0-beta.5.g18f3420031",
-    "axios": "^1.13.6",
-    "jsonwebtoken": "^9.0.3",
-    "jwks-rsa": "^4.0.1",
-    "object-path": "^0.11.8",
+    "@azure/core-auth": "1.10.1",
+    "@azure/msal-node": "5.0.6",
+    "@microsoft/agents-activity": "1.5.1",
+    "@microsoft/agents-telemetry": "1.5.1",
+    "axios": "1.15.0",
+    "jsonwebtoken": "9.0.3",
+    "jwks-rsa": "4.0.1",
+    "object-path": "0.11.8",
     "zod": "3.25.75"
   },
   "license": "MIT",
@@ -47,6 +48,6 @@
     "node": ">=20.0.0"
   },
   "devDependencies": {
-    "@types/object-path": "^0.11.4"
+    "@types/object-path": "0.11.4"
   }
 }

package/src/activityHandler.ts

@@ -2,7 +2,7 @@
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Licensed under the MIT License.
  */
-import { debug } from '@microsoft/agents-activity/logger'
+import { debug } from '@microsoft/agents-telemetry'
 import { TurnContext } from './turnContext'
 import { Activity, ActivityTypes, Channels, ExceptionHelper } from '@microsoft/agents-activity'
 import { Errors } from './errorHelper'

package/src/agent-client/agentClient.ts

@@ -1,9 +1,11 @@
 import { AuthConfiguration, MsalTokenProvider } from '../auth'
 import { Activity, ConversationReference, RoleTypes } from '@microsoft/agents-activity'
 import { v4 } from 'uuid'
-import { debug } from '@microsoft/agents-activity/logger'
+import { debug } from '@microsoft/agents-telemetry'
 import { ConversationState } from '../state'
 import { TurnContext } from '../turnContext'
+import { trace } from '@microsoft/agents-telemetry'
+import { AgentClientTraceDefinitions } from '../observability'
 
 const logger = debug('agents:agent-client')
 
@@ -68,56 +70,65 @@ export class AgentClient {
    * @throws Error if the request to the agent endpoint fails
    */
   public async postActivity (activity: Activity, authConfig: AuthConfiguration, conversationState: ConversationState, context: TurnContext): Promise<string> {
-    const activityCopy = activity.clone()
-    activityCopy.serviceUrl = this.agentClientConfig.serviceUrl
-    activityCopy.recipient = { ...activityCopy.recipient, role: RoleTypes.Skill }
-    activityCopy.relatesTo = {
-      serviceUrl: activity.serviceUrl,
-      activityId: activityCopy.id,
-      channelId: activityCopy.channelId!,
-      locale: activityCopy.locale,
-      conversation: {
-        id: activity.conversation!.id,
-        ...activityCopy.conversation
+    return trace(AgentClientTraceDefinitions.postActivity, async ({ record }) => {
+      record({
+        endpoint: this.agentClientConfig.endPoint,
+        clientId: this.agentClientConfig.clientId,
+      })
+      const activityCopy = activity.clone()
+      activityCopy.serviceUrl = this.agentClientConfig.serviceUrl
+      activityCopy.recipient = { ...activityCopy.recipient, role: RoleTypes.Skill }
+      activityCopy.relatesTo = {
+        serviceUrl: activity.serviceUrl,
+        activityId: activityCopy.id,
+        channelId: activityCopy.channelId!,
+        locale: activityCopy.locale,
+        conversation: {
+          id: activity.conversation!.id,
+          ...activityCopy.conversation
+        }
       }
-    }
-    activityCopy.conversation!.id = v4()
+      activityCopy.conversation!.id = v4()
 
-    const conversationDataAccessor = conversationState.createProperty<ConversationData>(activityCopy.conversation!.id)
-    const convRef = await conversationDataAccessor.set(context,
-      { conversationReference: activity.getConversationReference(), nameRequested: false },
-      { channelId: activityCopy.channelId!, conversationId: activityCopy.conversation!.id }
-    )
+      const conversationDataAccessor = conversationState.createProperty<ConversationData>(activityCopy.conversation!.id)
+      const convRef = await conversationDataAccessor.set(context,
+        { conversationReference: activity.getConversationReference(), nameRequested: false },
+        { channelId: activityCopy.channelId!, conversationId: activityCopy.conversation!.id }
+      )
 
-    const stateChanges = JSON.stringify(convRef)
-    logger.debug('stateChanges: ', stateChanges)
+      const stateChanges = JSON.stringify(convRef)
+      logger.debug('stateChanges: ', stateChanges)
 
-    const authProvider = new MsalTokenProvider(authConfig)
-    const token = await authProvider.getAccessToken(this.agentClientConfig.clientId)
+      const authProvider = new MsalTokenProvider(authConfig)
+      const token = await authProvider.getAccessToken(this.agentClientConfig.clientId)
 
-    logger.debug('agent request: ', activityCopy)
+      logger.debug('agent request: ', activityCopy)
 
-    let authHeader = '' // Allow anonymous auth.
+      let authHeader = '' // Allow anonymous auth.
 
-    if (token.trim().length > 0) {
-      authHeader = `Bearer ${token}`
-    }
+      if (token.trim().length > 0) {
+        authHeader = `Bearer ${token}`
+      }
 
-    await conversationState.saveChanges(context, false, { channelId: activityCopy.channelId!, conversationId: activityCopy.conversation!.id })
-    const response = await fetch(this.agentClientConfig.endPoint, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: authHeader,
-        'x-ms-conversation-id': activityCopy.conversation!.id
-      },
-      body: JSON.stringify(activityCopy)
+      await conversationState.saveChanges(context, false, { channelId: activityCopy.channelId!, conversationId: activityCopy.conversation!.id })
+      const response = await fetch(this.agentClientConfig.endPoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: authHeader,
+          'x-ms-conversation-id': activityCopy.conversation!.id
+        },
+        body: JSON.stringify(activityCopy)
+      })
+
+      record({ httpStatusCode: response.status.toString() })
+
+      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}`)
+      }
+      return response.statusText
     })
-    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}`)
-    }
-    return response.statusText
   }
 
   /**

package/src/agent-client/agentResponseHandler.ts

@@ -5,7 +5,7 @@ import { Request, Response, Application } from 'express'
 import { TurnContext } from '../turnContext'
 import { v4 } from 'uuid'
 import { normalizeIncomingActivity } from '../activityWireCompat'
-import { debug } from '@microsoft/agents-activity/logger'
+import { debug } from '@microsoft/agents-telemetry'
 import { ConversationState } from '../state'
 
 const logger = debug('agents:agent-client')

package/src/app/agentApplication.ts

@@ -3,12 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import { Activity, ActivityTypes, ConversationReference } from '@microsoft/agents-activity'
+import { Activity, ActivityTypes, ConversationReference, ExceptionHelper } from '@microsoft/agents-activity'
 import { ResourceResponse } from '../connector-client'
-import { debug } from '@microsoft/agents-activity/logger'
 import { TurnContext } from '../turnContext'
 import { AdaptiveCardsActions } from './adaptiveCards'
-import { AgentApplicationOptions } from './agentApplicationOptions'
+import { AgentApplicationOptions, TypingTimingOptions } from './agentApplicationOptions'
 import { ConversationUpdateEvents } from './conversationUpdateEvents'
 import { AgentExtension } from './extensions'
 import { RouteHandler } from './routeHandler'
@@ -20,11 +19,30 @@ 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 { trace, debug } from '@microsoft/agents-telemetry'
+import { AgentApplicationTraceDefinitions } from '../observability'
+import { Errors } from '../errorHelper'
 
 const logger = debug('agents:app')
 
-const TYPING_TIMER_DELAY = 1000
+// Resend typing every 4 seconds to stay ahead of the ~5 second timeout seen in
+// Web Chat and Microsoft 365. Teams may keep typing indicators visible longer.
+const DEFAULT_TYPING_INITIAL_DELAY = 0
+const DEFAULT_TYPING_INTERVAL = 4000
+const TYPING_TIMER_STATE_KEY = Symbol('typingTimerState')
+
+type TypingTimerState = {
+  timer?: NodeJS.Timeout
+  lastSend: Promise<unknown>
+  stop: () => void
+}
+
+type StreamInfoEntity = {
+  type?: string
+  streamType?: string
+}
 
 /**
  * Event handler function type for application events.
@@ -74,9 +92,9 @@ export class AgentApplication<TState extends TurnState> {
   protected readonly _beforeTurn: ApplicationEventHandler<TState>[] = []
   protected readonly _afterTurn: ApplicationEventHandler<TState>[] = []
   private readonly _adapter?: CloudAdapter
-  private readonly _authorizationManager?: AuthorizationManager
-  private readonly _authorization?: Authorization
-  private _typingTimer: NodeJS.Timeout | undefined
+  private readonly _authorizationManager: AuthorizationManager
+  private readonly _authorization: Authorization
+  private readonly _proactive?: Proactive<TState>
   protected readonly _extensions: AgentExtension<TState>[] = []
   private readonly _adaptiveCards: AdaptiveCardsActions<TState>
 
@@ -112,6 +130,7 @@ export class AgentApplication<TState extends TurnState> {
       ...options,
       turnStateFactory: options?.turnStateFactory || (() => new TurnState() as TState),
       startTypingTimer: options?.startTypingTimer !== undefined ? options.startTypingTimer : false,
+      typing: options?.typing || undefined,
       longRunningMessages: options?.longRunningMessages !== undefined ? options.longRunningMessages : false,
       removeRecipientMention: options?.removeRecipientMention !== undefined ? options.removeRecipientMention : true,
       transcriptLogger: options?.transcriptLogger || undefined,
@@ -125,9 +144,12 @@ export class AgentApplication<TState extends TurnState> {
       this._adapter = new CloudAdapter()
     }
 
-    if (this._options.authorization) {
-      this._authorizationManager = new AuthorizationManager(this, this._adapter.connectionManager)
-      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) {
@@ -141,7 +163,11 @@ export class AgentApplication<TState extends TurnState> {
         this._adapter?.use(new TranscriptLoggerMiddleware(this._options.transcriptLogger))
       }
     }
+
     logger.debug('AgentApplication created with options:', this._options)
+
+    this._authorizationManager = new AuthorizationManager(this, this._adapter.connectionManager)
+    this._authorization = new UserAuthorization(this._authorizationManager)
   }
 
   /**
@@ -151,12 +177,33 @@ export class AgentApplication<TState extends TurnState> {
    * @throws Error if no authentication options were configured.
    */
   public get authorization (): Authorization {
-    if (!this._authorization) {
+    if (this._authorizationManager.handlers.length === 0) {
       throw new Error('The Application.authorization property is unavailable because no authorization options were configured.')
     }
     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.
    *
@@ -605,6 +652,9 @@ export class AgentApplication<TState extends TurnState> {
     const { authorized, context } = await this.handleAuthorization(turnContext)
 
     if (!authorized) {
+      const managed = trace(AgentApplicationTraceDefinitions.run)
+      managed.record({ authorized, activity: context.activity })
+      managed.end()
       // 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
     }
@@ -644,54 +694,75 @@ export class AgentApplication<TState extends TurnState> {
    * 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)
-      }
+    return trace(AgentApplicationTraceDefinitions.run, async ({ record }) => {
+      record({ authorized: true, activity: context.activity })
 
-      if (this._options.removeRecipientMention && context.activity.type === ActivityTypes.Message) {
-        context.activity.removeRecipientMention()
-      }
+      try {
+        if (this._options.startTypingTimer) {
+          this.startTypingTimer(context)
+        }
 
-      if (this._options.normalizeMentions && context.activity.type === ActivityTypes.Message) {
-        context.activity.normalizeMentions()
-      }
+        if (this._options.removeRecipientMention && context.activity.type === ActivityTypes.Message) {
+          context.activity.removeRecipientMention()
+        }
 
-      const { storage, turnStateFactory } = this._options
-      const state = turnStateFactory()
-      await state.load(context, storage)
+        if (this._options.normalizeMentions && context.activity.type === ActivityTypes.Message) {
+          context.activity.normalizeMentions()
+        }
 
-      const route = await this.getRoute(context)
+        const { storage, turnStateFactory } = this._options
+        const state = turnStateFactory()
+        await state.load(context, storage)
 
-      if (!route) {
-        logger.debug('No matching route found for activity:', context.activity)
-        return false
-      }
+        const route = await this.getRoute(context)
 
-      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)
+        record({ routeMatched: route !== undefined })
+
+        if (!route) {
+          logger.debug('No matching route found for activity:', context.activity)
+          return false
         }
-      }
 
-      if (!(await this.callEventHandlers(context, state, this._beforeTurn))) {
-        await state.save(context, storage)
-        return false
-      }
+        const fileDownloaders = this._options.fileDownloaders
+        if (Array.isArray(fileDownloaders) && fileDownloaders.length > 0) {
+          await trace(AgentApplicationTraceDefinitions.downloadFiles, async ({ record }) => {
+            record({ attachmentsCount: context.activity.attachments?.length })
+            for (let i = 0; i < fileDownloaders.length; i++) {
+              await fileDownloaders[i].downloadAndStoreFiles(context, state)
+            }
+          })
+        }
 
-      await route.handler(context, state)
+        if (this._beforeTurn.length > 0) {
+          await trace(AgentApplicationTraceDefinitions.beforeTurn, async () => {
+            if (!(await this.callEventHandlers(context, state, this._beforeTurn))) {
+              await state.save(context, storage)
+              return false
+            }
+          })
+        }
 
-      if (await this.callEventHandlers(context, state, this._afterTurn)) {
-        await state.save(context, storage)
-      }
+        await trace(AgentApplicationTraceDefinitions.routeHandler, async ({ record }) => {
+          record({ isInvoke: route.isInvokeRoute, isAgentic: route.isAgenticRoute })
+          await route.handler(context, state)
+        })
 
-      return true
-    } catch (err: any) {
-      logger.error(err)
-      throw err
-    } finally {
-      this.stopTypingTimer()
-    }
+        if (this._afterTurn.length > 0) {
+          await trace(AgentApplicationTraceDefinitions.afterTurn, async () => {
+            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(context)
+      }
+    })
   }
 
   /**
@@ -766,43 +837,84 @@ export class AgentApplication<TState extends TurnState> {
    *
    */
   public startTypingTimer (context: TurnContext): void {
-    if (context.activity.type === ActivityTypes.Message && !this._typingTimer) {
-      let timerRunning = true
-      context.onSendActivities(async (context, activities, next) => {
-        if (timerRunning) {
-          for (let i = 0; i < activities.length; i++) {
-            if (activities[i].type === ActivityTypes.Message || activities[i].channelData?.streamType) {
-              this.stopTypingTimer()
-              timerRunning = false
-              await lastSend
-              break
-            }
-          }
+    const turnState = context.turnState
+    const typingOptions = this.getTypingTimingOptions(context)
+    // Timer state is stored on the current turn so concurrent turns stay isolated.
+    const currentState = () => turnState.get<TypingTimerState>(TYPING_TIMER_STATE_KEY)
+
+    if (context.activity.type !== ActivityTypes.Message || currentState()) {
+      return
+    }
+
+    const state: TypingTimerState = {
+      lastSend: Promise.resolve(),
+      stop: () => {
+        if (state.timer) {
+          clearTimeout(state.timer)
+          state.timer = undefined
         }
 
-        return next()
-      })
+        turnState.delete(TYPING_TIMER_STATE_KEY)
+      }
+    }
 
-      let lastSend: Promise<any> = Promise.resolve()
-      const onTimeout = async () => {
-        try {
-          lastSend = context.sendActivity(Activity.fromObject({ type: ActivityTypes.Typing }))
-          await lastSend
-        } catch (err: any) {
+    turnState.set(TYPING_TIMER_STATE_KEY, state)
+
+    context.onSendActivities(async (context, activities, next) => {
+      // Any real response or stream start ends the typing loop for this turn.
+      if (activities.some(activity => activity.type === ActivityTypes.Message || this.getStreamType(activity) !== undefined)) {
+        state.stop()
+        // Wait for any in-flight typing send to finish before sending the real response.
+        await state.lastSend.catch((err: any) => {
           logger.error(err)
-          this._typingTimer = undefined
-          timerRunning = false
-          lastSend = Promise.resolve()
-        }
+        })
+      }
 
-        if (timerRunning) {
-          this._typingTimer = setTimeout(onTimeout, TYPING_TIMER_DELAY)
-        }
+      return next()
+    })
+
+    const onTimeout = async () => {
+      try {
+        state.lastSend = this.sendTypingActivity(context)
+        await state.lastSend
+      } catch (err: any) {
+        logger.error(err)
+        state.lastSend = Promise.resolve()
+        state.stop()
+        return
       }
-      this._typingTimer = setTimeout(onTimeout, TYPING_TIMER_DELAY)
+
+      // Only reschedule if this turn still owns the active timer state.
+      if (currentState() === state) {
+        state.timer = setTimeout(onTimeout, typingOptions.intervalMs)
+      }
+    }
+
+    state.timer = setTimeout(onTimeout, typingOptions.initialDelayMs)
+  }
+
+  private getTypingTimingOptions (context: TurnContext): Required<TypingTimingOptions> {
+    const channelId = context.activity.channelId || context.activity.channelIdChannel || ''
+    const channelOptions = channelId ? this._options.typing?.channelStrategies?.[channelId] : undefined
+
+    return {
+      initialDelayMs: channelOptions?.initialDelayMs ?? this._options.typing?.initialDelayMs ?? DEFAULT_TYPING_INITIAL_DELAY,
+      intervalMs: channelOptions?.intervalMs ?? this._options.typing?.intervalMs ?? DEFAULT_TYPING_INTERVAL
     }
   }
 
+  private getStreamType (activity: Activity): string | undefined {
+    const streamingEntity = activity.entities?.find((entity) => (entity as StreamInfoEntity).type === 'streaminfo') as StreamInfoEntity | undefined
+    return streamingEntity?.streamType ?? activity.channelData?.streamType
+  }
+
+  private async sendTypingActivity (context: TurnContext): Promise<ResourceResponse[] | undefined> {
+    const conversationReference = context.activity.getConversationReference()
+    const typingActivity = Activity.fromObject({ type: ActivityTypes.Typing }).applyConversationReference(conversationReference)
+
+    return await context.adapter.sendActivities(context, [typingActivity])
+  }
+
   /**
    * Registers an extension with the application.
    *
@@ -838,23 +950,37 @@ export class AgentApplication<TState extends TurnState> {
    * @returns void
    *
    * @remarks
-   * This method clears the typing indicator timer to prevent further typing indicators
-   * from being sent. It's typically called automatically when a message is sent, but
-   * can also be called manually to stop the typing indicator.
+   * Calling this overload without a context is deprecated. It only logs a warning and does not stop any timer.
+   *
+   * @deprecated Pass the current TurnContext to stop only that turn's typing timer.
+   */
+  public stopTypingTimer (): void
+
+  /**
+   * Stops the typing indicator timer for the provided turn context.
+   *
+   * @param context - The turn context whose typing timer should be stopped.
+   * @returns void
+   *
+   * @remarks
+   * This method clears the typing indicator timer for the current turn to prevent further typing indicators
+   * from being sent. It's typically called automatically when a message is sent, but can also be called manually.
    *
    * @example
    * ```typescript
-   * app.startTypingTimer(turnContext);
+   * app.startTypingTimer(turnContext)
    * // Do some processing...
-   * app.stopTypingTimer(); // Manually stop the typing indicator
+   * app.stopTypingTimer(turnContext)
    * ```
-   *
    */
-  public stopTypingTimer (): void {
-    if (this._typingTimer) {
-      clearTimeout(this._typingTimer)
-      this._typingTimer = undefined
+  public stopTypingTimer (context: TurnContext): void
+  public stopTypingTimer (context?: TurnContext): void {
+    if (!context) {
+      logger.warn('Application.stopTypingTimer() without a context is deprecated. Pass the current TurnContext instead.')
+      return
     }
+
+    context.turnState.get<TypingTimerState>(TYPING_TIMER_STATE_KEY)?.stop()
   }
 
   /**

package/src/app/agentApplicationBuilder.ts

@@ -7,7 +7,9 @@ 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'
+import { TypingOptions } from './agentApplicationOptions'
 
 /**
  * Builder class for creating and configuring AgentApplication instances.
@@ -49,10 +51,20 @@ export class AgentApplicationBuilder<TState extends TurnState = TurnState> {
    * @param startTypingTimer Whether to show typing indicators
    * @returns This builder instance for chaining
    */
-  // public setStartTypingTimer (startTypingTimer: boolean): this {
-  //   this._options.startTypingTimer = startTypingTimer
-  //   return this
-  // }
+  public setStartTypingTimer (startTypingTimer: boolean): this {
+    this._options.startTypingTimer = startTypingTimer
+    return this
+  }
+
+  /**
+   * Configures timing behavior for automatic typing indicators.
+   * @param typing Typing timer options
+   * @returns This builder instance for chaining
+   */
+  public withTyping (typing: TypingOptions): this {
+    this._options.typing = typing
+    return this
+  }
 
   /**
    * Sets authentication options for the AgentApplication.
@@ -64,6 +76,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