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

package/src/app/proactive/proactive.ts

@@ -0,0 +1,481 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import type { Activity } from '@microsoft/agents-activity'
+import type { ResourceResponse } from '../../connector-client'
+import type { BaseAdapter } from '../../baseAdapter'
+import type { TurnContext } from '../../turnContext'
+import type { TurnState } from '../turnState'
+import type { RouteHandler } from '../routeHandler'
+import type { Storage } from '../../storage/storage'
+import type { AgentApplication } from '../agentApplication'
+import type { ProactiveOptions } from './proactiveOptions'
+import type { CreateConversationOptions } from './createConversationOptions'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Conversation } from './conversation'
+import { debug } from '@microsoft/agents-activity/logger'
+import { Errors } from '../../errorHelper'
+
+const logger = debug('agents:proactive')
+const STORAGE_KEY_PREFIX = 'proactive/conversations/'
+
+/**
+ * Provides methods for storing, retrieving, and managing conversation references to enable
+ * proactive messaging scenarios. Supports sending activities and continuing conversations outside
+ * the standard request/response flow using stored conversation references.
+ *
+ * @remarks
+ * Use the `Proactive` class to implement scenarios where an agent needs to initiate conversations
+ * or send messages to users without an incoming activity, such as notifications or scheduled alerts.
+ * Some operations require that conversation references be stored using {@link storeConversation}
+ * before they can be used.
+ *
+ * Access via `app.proactive` after configuring `proactive` in {@link AgentApplicationOptions}.
+ */
+export class Proactive<TState extends TurnState> {
+  /**
+   * `activity.valueType` that indicates additional key/values for the ContinueConversation event.
+   */
+  static readonly ContinueConversationValueType = 'application/vnd.microsoft.activity.continueconversation+json'
+
+  private readonly _app: AgentApplication<TState>
+  private readonly _options: ProactiveOptions
+  private readonly _storage?: Storage
+
+  constructor (app: AgentApplication<TState>, options: ProactiveOptions) {
+    this._app = app
+    this._options = options
+    this._storage = options.storage
+  }
+
+  private requireStorage (): Storage {
+    if (!this._storage) {
+      throw ExceptionHelper.generateException(Error, Errors.ProactiveStorageRequired)
+    }
+    return this._storage
+  }
+
+  private requireAppStorage (): Storage {
+    const storage = this._app.options.storage
+    if (!storage) {
+      throw ExceptionHelper.generateException(Error, Errors.ProactiveAppStorageRequired)
+    }
+    return storage
+  }
+
+  // ---------------------------------------------------------------------------
+  // Conversation reference storage
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Stores the current conversation reference from a live {@link TurnContext} in proactive storage.
+   *
+   * @param context - The context object for the current turn, containing activity and conversation
+   *   information.
+   * @returns The conversation ID that can be used to retrieve the reference in future operations.
+   * @example
+   * ```typescript
+   * // Inside an onMessage handler — save the conversation so we can message later
+   * app.onActivity('message', async (ctx, state) => {
+   *   const convId = await app.proactive.storeConversation(ctx)
+   *   await ctx.sendActivity(`Conversation stored. ID: ${convId}`)
+   * })
+   * ```
+   */
+  storeConversation (context: TurnContext): Promise<string>
+  /**
+   * Stores an explicit {@link Conversation} object in proactive storage.
+   *
+   * @param conversation - The conversation reference record to store.
+   * @returns The conversation ID that can be used to retrieve the reference in future operations.
+   * @throws If the conversation fails validation (missing `conversation.id`, `serviceUrl`, or
+   *   `claims.aud`).
+   * @example
+   * ```typescript
+   * // Build a Conversation manually and store it
+   * const conv = ConversationBuilder
+   *   .create('my-app-id', 'msteams')
+   *   .withUser('user-aad-id')
+   *   .withConversationId('19:existing-thread-id@thread.tacv2')
+   *   .build()
+   * const convId = await app.proactive.storeConversation(conv)
+   * ```
+   */
+  storeConversation (conversation: Conversation): Promise<string>
+  async storeConversation (contextOrConversation: TurnContext | Conversation): Promise<string> {
+    const conv =
+      contextOrConversation instanceof Conversation
+        ? contextOrConversation
+        : new Conversation(contextOrConversation as TurnContext)
+
+    conv.validate()
+    const id = conv.reference.conversation.id
+    await this.requireStorage().write({ [`${STORAGE_KEY_PREFIX}${id}`]: { reference: conv.reference, claims: conv.claims } })
+    return id
+  }
+
+  /**
+   * Retrieves the stored {@link Conversation} associated with the given conversation ID.
+   *
+   * @param conversationId - The unique identifier of the conversation to retrieve.
+   * @returns The stored `Conversation`, or `undefined` if no record exists for that ID.
+   * @example
+   * ```typescript
+   * const conv = await app.proactive.getConversation(convId)
+   * if (conv) {
+   *   await app.proactive.sendActivity(adapter, conv, { text: 'Hello!' })
+   * }
+   * ```
+   */
+  async getConversation (conversationId: string): Promise<Conversation | undefined> {
+    const result = await this.requireStorage().read([`${STORAGE_KEY_PREFIX}${conversationId}`])
+    const stored = result[`${STORAGE_KEY_PREFIX}${conversationId}`] as { reference: any; claims: any } | undefined
+    if (!stored) return undefined
+    return new Conversation(stored.claims, stored.reference)
+  }
+
+  /**
+   * Retrieves the stored {@link Conversation} for the given ID, throwing if no record is found.
+   *
+   * @param conversationId - The unique identifier of the conversation to retrieve.
+   * @returns The stored `Conversation`.
+   * @throws `Error` if no conversation reference is found for the specified ID.
+   * @example
+   * ```typescript
+   * // Use when absence of the conversation should be treated as an error
+   * const conv = await app.proactive.getConversationOrThrow(convId)
+   * await app.proactive.sendActivity(adapter, conv, { text: 'Alert: your report is ready.' })
+   * ```
+   */
+  async getConversationOrThrow (conversationId: string): Promise<Conversation> {
+    const conv = await this.getConversation(conversationId)
+    if (!conv) {
+      throw ExceptionHelper.generateException(Error, Errors.ProactiveConversationNotFound, undefined, { conversationId })
+    }
+    return conv
+  }
+
+  /**
+   * Deletes the stored conversation reference for the given conversation ID.
+   *
+   * @param conversationId - The unique identifier of the conversation whose reference should be
+   *   deleted.
+   * @remarks If no record exists for the given ID, no action is taken.
+   * @example
+   * ```typescript
+   * // Clean up after a conversation has ended
+   * app.onActivity('endOfConversation', async (ctx, state) => {
+   *   await app.proactive.deleteConversation(ctx.activity.conversation.id)
+   * })
+   * ```
+   */
+  async deleteConversation (conversationId: string): Promise<void> {
+    await this.requireStorage().delete([`${STORAGE_KEY_PREFIX}${conversationId}`])
+  }
+
+  // ---------------------------------------------------------------------------
+  // Send activity
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Sends an activity to a stored conversation, looking it up by ID.
+   *
+   * @param adapter - The channel adapter used to send the activity.
+   * @param conversationId - The ID of a conversation previously stored via {@link storeConversation}.
+   * @param activity - The activity to send. If `type` is not set it defaults to `'message'`.
+   * @returns A {@link ResourceResponse} with the ID of the sent activity.
+   * @throws `Error` if no conversation reference is found for the specified ID.
+   * @example
+   * ```typescript
+   * // Send a notification using a previously stored conversation ID
+   * await app.proactive.sendActivity(adapter, storedConvId, { text: 'Your order has shipped!' })
+   * ```
+   */
+  sendActivity (adapter: BaseAdapter, conversationId: string, activity: Partial<Activity>): Promise<ResourceResponse>
+  /**
+   * Sends an activity to an existing conversation using the provided {@link Conversation} reference.
+   *
+   * @param adapter - The channel adapter used to send the activity.
+   * @param conversation - A `Conversation` instance created via its constructor or
+   *   {@link ConversationBuilder}.
+   * @param activity - The activity to send. If `type` is not set it defaults to `'message'`.
+   * @returns A {@link ResourceResponse} with the ID of the sent activity.
+   * @example
+   * ```typescript
+   * // Build a Conversation from a stored reference and send a message
+   * const conv = await app.proactive.getConversationOrThrow(convId)
+   * const response = await app.proactive.sendActivity(adapter, conv, { text: 'Hello from the agent!' })
+   * console.log('Sent activity ID:', response.id)
+   * ```
+   */
+  sendActivity (adapter: BaseAdapter, conversation: Conversation, activity: Partial<Activity>): Promise<ResourceResponse>
+  async sendActivity (
+    adapter: BaseAdapter,
+    conversationOrId: Conversation | string,
+    activity: Partial<Activity>
+  ): Promise<ResourceResponse> {
+    const conv =
+      typeof conversationOrId === 'string'
+        ? await this.getConversationOrThrow(conversationOrId)
+        : conversationOrId
+
+    const activityToSend: Partial<Activity> = { type: 'message', ...activity }
+
+    logger.info('sendActivity: conversation=%s channel=%s serviceUrl=%s',
+      conv.reference.conversation.id, conv.reference.channelId, conv.reference.serviceUrl)
+
+    let response: ResourceResponse | undefined
+    let caughtError: unknown
+
+    await adapter.continueConversation(conv.identity, conv.reference, async (ctx: TurnContext) => {
+      try {
+        const result = await ctx.sendActivity(activityToSend as Activity)
+        response = result as ResourceResponse
+      } catch (err) {
+        caughtError = err
+      }
+    })
+
+    if (caughtError !== undefined) {
+      logger.warn('sendActivity: failed for conversation=%s: %s', conv.reference.conversation.id, caughtError)
+      throw caughtError
+    }
+    if (response === undefined) throw ExceptionHelper.generateException(Error, Errors.ProactiveSendActivityNoResponse)
+    logger.debug('sendActivity: sent activity id=%s', response.id)
+    return response
+  }
+
+  // ---------------------------------------------------------------------------
+  // Full-turn handler (loads TurnState, handles auth tokens)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Continues a stored conversation by executing the given handler within the context of that
+   * conversation, looking it up by ID.
+   *
+   * See the {@link Conversation} overload for full details.
+   *
+   * @param adapter - The channel adapter used to continue the conversation.
+   * @param conversationId - The ID of a conversation previously stored via {@link storeConversation}.
+   * @param handler - The route handler to execute within the continued conversation context.
+   * @param autoSignInHandlers - Optional list of OAuth connection names whose tokens should be
+   *   acquired before invoking the handler.
+   * @param continuationActivity - Optional activity fields merged into the continuation activity,
+   *   making them available on `ctx.activity` inside the handler (e.g. `value`, `valueType`).
+   * @throws `Error` if no conversation reference is found for the specified ID.
+   * @example
+   * ```typescript
+   * // Scheduled job: send a daily digest to all stored conversations
+   * for (const convId of storedIds) {
+   *   await app.proactive.continueConversation(adapter, convId, async (ctx, state) => {
+   *     await ctx.sendActivity('Here is your daily digest...')
+   *   })
+   * }
+   * ```
+   */
+  continueConversation (adapter: BaseAdapter, conversationId: string, handler: RouteHandler<TState>, autoSignInHandlers?: string[], continuationActivity?: Partial<Activity>): Promise<void>
+  /**
+   * Continues an existing conversation by executing the given handler within the context of the
+   * provided {@link Conversation} reference. The handler receives a {@link TurnContext} and a
+   * freshly loaded {@link TurnState} scoped to the original conversation, enabling the agent to
+   * respond as if replying to an incoming activity.
+   *
+   * @remarks
+   * Exceptions thrown inside the handler are captured and re-thrown after the adapter callback
+   * completes, since the adapter would otherwise silently swallow them.
+   *
+   * If `autoSignInHandlers` are supplied and the application has user authorization configured,
+   * tokens are acquired before the handler is called. If not all tokens are available and
+   * `proactiveOptions.failOnUnsignedInConnections` is not `false`, an error is thrown.
+   *
+   * @param adapter - The channel adapter used to continue the conversation.
+   * @param conversation - A `Conversation` instance created via its constructor or
+   *   {@link ConversationBuilder}.
+   * @param handler - The route handler to execute within the continued conversation context.
+   * @param autoSignInHandlers - Optional list of OAuth connection names whose tokens should be
+   *   acquired before invoking the handler.
+   * @param continuationActivity - Optional activity fields merged into the continuation activity,
+   *   making them available on `ctx.activity` inside the handler (e.g. `value`, `valueType`).
+   * @example
+   * ```typescript
+   * // Continue a conversation with a custom value payload
+   * const conv = await app.proactive.getConversationOrThrow(convId)
+   * await app.proactive.continueConversation(
+   *   adapter,
+   *   conv,
+   *   async (ctx, state) => {
+   *     const payload = ctx.activity.value as { alertType: string }
+   *     await ctx.sendActivity(`Alert triggered: ${payload.alertType}`)
+   *   },
+   *   undefined,
+   *   { value: { alertType: 'threshold-exceeded' }, valueType: Proactive.ContinueConversationValueType }
+   * )
+   * ```
+   */
+  continueConversation (adapter: BaseAdapter, conversation: Conversation, handler: RouteHandler<TState>, autoSignInHandlers?: string[], continuationActivity?: Partial<Activity>): Promise<void>
+  async continueConversation (
+    adapter: BaseAdapter,
+    conversationOrId: Conversation | string,
+    handler: RouteHandler<TState>,
+    autoSignInHandlers?: string[],
+    continuationActivity?: Partial<Activity>
+  ): Promise<void> {
+    const conv =
+      typeof conversationOrId === 'string'
+        ? await this.getConversationOrThrow(conversationOrId)
+        : conversationOrId
+
+    logger.info('continueConversation: conversation=%s channel=%s serviceUrl=%s',
+      conv.reference.conversation.id, conv.reference.channelId, conv.reference.serviceUrl)
+
+    let caughtError: unknown
+
+    await adapter.continueConversation(conv.identity, conv.reference, async (ctx: TurnContext) => {
+      try {
+        // Merge caller-supplied activity fields (e.g. value, valueType) into the
+        // continuation activity so the handler can read request-time parameters.
+        if (continuationActivity) {
+          Object.assign(ctx.activity, continuationActivity)
+        }
+
+        const state = this._app.options.turnStateFactory()
+        await state.load(ctx, this.requireAppStorage())
+
+        // Token acquisition (optional — only when auth is configured)
+        if (autoSignInHandlers?.length && this._app.hasUserAuthorization) {
+          logger.debug('continueConversation: acquiring tokens for handlers: %o', autoSignInHandlers)
+          const results = await Promise.all(
+            autoSignInHandlers.map((handlerId) =>
+              this._app.authorization.getToken(ctx, handlerId).catch(() => ({ token: undefined }))
+            )
+          )
+          const allAcquired = results.every((r) => !!r.token)
+          if (!allAcquired) {
+            logger.warn('continueConversation: not all tokens acquired for conversation=%s handlers=%o',
+              conv.reference.conversation.id, autoSignInHandlers)
+            if (this._options.failOnUnsignedInConnections !== false) {
+              throw ExceptionHelper.generateException(Error, Errors.ProactiveNotAllTokensAcquired)
+            }
+          }
+        }
+
+        await handler(ctx, state)
+        await state.save(ctx, this.requireAppStorage())
+      } catch (err) {
+        caughtError = err
+      } finally {
+        if ((ctx as any).streamingResponse?.isStreamStarted?.()) {
+          await (ctx as any).streamingResponse.endStream()
+        }
+      }
+    })
+
+    if (caughtError !== undefined) {
+      logger.warn('continueConversation: failed for conversation=%s: %s', conv.reference.conversation.id, caughtError)
+      throw caughtError
+    }
+    logger.debug('continueConversation: complete for conversation=%s', conv.reference.conversation.id)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Create new conversation
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Creates a new conversation using the specified channel adapter and conversation options.
+   *
+   * @remarks
+   * This wraps `CloudAdapter.createConversationAsync()`, which requires real network connectivity
+   * and authentication. The provided adapter must implement
+   * `createConversationAsync()`; a `TypeError` is thrown if it does not.
+   *
+   * If `createOptions.storeConversation` is `true`, the resulting {@link Conversation} is
+   * automatically stored via {@link storeConversation} so it can be retrieved by ID later.
+   *
+   * If a `handler` is provided it is executed within the newly created conversation, giving the
+   * agent a chance to send an initial message or load state.
+   *
+   * @param adapter - The channel adapter used to create the conversation. Must implement
+   *   `createConversationAsync()` (i.e. a `CloudAdapter` instance).
+   * @param createOptions - Details required to create the conversation, including identity, channel,
+   *   service URL, OAuth scope, and `ConversationParameters`. Build with
+   *   {@link CreateConversationOptionsBuilder}.
+   * @param handler - Optional route handler executed immediately after the conversation is created.
+   * @returns The newly created {@link Conversation}.
+   * @throws `TypeError` if the adapter does not implement `createConversationAsync()`.
+   * @example
+   * ```typescript
+   * // Initiate a new 1:1 conversation with a Teams user and send a welcome message
+   * const opts = CreateConversationOptionsBuilder
+   *   .create(process.env.APP_ID!, 'msteams')
+   *   .withUser('user-aad-object-id')
+   *   .withTenantId('tenant-id')
+   *   .storeConversation(true)
+   *   .build()
+   *
+   * const conv = await app.proactive.createConversation(adapter, opts, async (ctx, state) => {
+   *   await ctx.sendActivity('Hi! I have an update for you.')
+   * })
+   * console.log('New conversation ID:', conv.reference.conversation.id)
+   * ```
+   */
+  async createConversation (
+    adapter: BaseAdapter,
+    createOptions: CreateConversationOptions,
+    handler?: RouteHandler<TState>
+  ): Promise<Conversation> {
+    if (!createOptions.parameters.members?.length) {
+      throw ExceptionHelper.generateException(Error, Errors.ProactiveMembersRequired)
+    }
+
+    // CloudAdapter.createConversationAsync(agentAppId, channelId, serviceUrl, audience, params, logic)
+    // The logic callback IS the handler — context is created internally by the adapter.
+    const cloudAdapter = adapter as any
+    if (typeof cloudAdapter.createConversationAsync !== 'function') {
+      throw ExceptionHelper.generateException(TypeError, Errors.ProactiveCloudAdapterRequired)
+    }
+    logger.info('createConversation: channel=%s serviceUrl=%s members=%d',
+      createOptions.channelId, createOptions.serviceUrl, createOptions.parameters.members?.length ?? 0)
+
+    let capturedConv: Conversation | undefined
+    let caughtError: unknown
+
+    await cloudAdapter.createConversationAsync(
+      createOptions.identity.aud,
+      createOptions.channelId,
+      createOptions.serviceUrl,
+      createOptions.scope,
+      createOptions.parameters,
+      async (ctx: TurnContext) => {
+        try {
+          const conv = new Conversation(createOptions.identity, ctx.activity.getConversationReference())
+          capturedConv = conv
+          logger.debug('createConversation: created conversation=%s', conv.reference.conversation.id)
+
+          if (createOptions.storeConversation) {
+            await this.storeConversation(conv)
+          }
+
+          if (handler) {
+            const state = this._app.options.turnStateFactory()
+            await state.load(ctx, this.requireAppStorage())
+            await handler(ctx, state)
+            await state.save(ctx, this.requireAppStorage())
+          }
+        } catch (err) {
+          caughtError = err
+        }
+      }
+    )
+
+    if (caughtError !== undefined) {
+      logger.warn('createConversation: failed for channel=%s: %s', createOptions.channelId, caughtError)
+      throw caughtError
+    }
+
+    if (!capturedConv) {
+      throw ExceptionHelper.generateException(Error, Errors.ProactiveCallbackNotInvoked)
+    }
+    return capturedConv
+  }
+}

package/src/app/proactive/proactiveOptions.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import type { Storage } from '../../storage/storage'
+
+/**
+ * Configuration for the proactive messaging subsystem.
+ */
+export interface ProactiveOptions {
+  /**
+   * Storage backend for persisting conversation references.
+   *
+   * If omitted, falls back to `AgentApplicationOptions.storage`.
+   * A warning is logged when the fallback is used.
+   * Throws at initialization time if neither is configured.
+   */
+  storage?: Storage
+
+  /**
+   * When `true` (default), `continueConversation()` throws if any requested
+   * token handler's user has not previously signed in.
+   */
+  failOnUnsignedInConnections?: boolean
+}

package/src/errorHelper.ts

@@ -660,6 +660,114 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'Invalid action value: {error}'
   },
 
+  // ============================================================================
+  // Proactive Messaging Errors (-120740 to -120799)
+  // ============================================================================
+
+  /**
+   * Error thrown when Application.proactive is accessed but no storage was configured.
+   */
+  ProactivePropertyUnavailable: {
+    code: -120740,
+    description: 'The Application.proactive property is unavailable because no storage was configured. Set options.storage or options.proactive.storage.'
+  },
+
+  /**
+   * Error thrown when a proactive storage operation is attempted without a storage backend.
+   */
+  ProactiveStorageRequired: {
+    code: -120741,
+    description: 'This proactive operation requires a storage backend. Set options.storage or options.proactive.storage.'
+  },
+
+  /**
+   * Error thrown when a conversation is not found in proactive storage.
+   */
+  ProactiveConversationNotFound: {
+    code: -120742,
+    description: "Conversation '{conversationId}' was not found in proactive storage."
+  },
+
+  /**
+   * Error thrown when sendActivity does not receive a ResourceResponse from the adapter.
+   */
+  ProactiveSendActivityNoResponse: {
+    code: -120743,
+    description: 'sendActivity: adapter did not return a ResourceResponse.'
+  },
+
+  /**
+   * Error thrown when not all token handlers have a signed-in user for proactive continuation.
+   */
+  ProactiveNotAllTokensAcquired: {
+    code: -120744,
+    description: 'Not all token handlers have a signed-in user.'
+  },
+
+  /**
+   * Error thrown when createConversation is called without any members.
+   */
+  ProactiveMembersRequired: {
+    code: -120745,
+    description: 'createConversation: at least one member must be specified in parameters.members.'
+  },
+
+  /**
+   * Error thrown when the adapter passed to createConversation does not support createConversationAsync.
+   */
+  ProactiveCloudAdapterRequired: {
+    code: -120746,
+    description: 'createConversation requires a CloudAdapter. The provided adapter does not implement createConversationAsync().'
+  },
+
+  /**
+   * Error thrown when createConversationAsync completes without invoking its callback.
+   */
+  ProactiveCallbackNotInvoked: {
+    code: -120747,
+    description: 'createConversation: createConversationAsync completed without invoking its callback.'
+  },
+
+  /**
+   * Error thrown when a Conversation reference is missing conversation.id.
+   */
+  ConversationInvalidId: {
+    code: -120748,
+    description: 'Conversation is invalid: reference.conversation.id is required.'
+  },
+
+  /**
+   * Error thrown when a Conversation reference is missing serviceUrl.
+   */
+  ConversationInvalidServiceUrl: {
+    code: -120749,
+    description: 'Conversation is invalid: reference.serviceUrl is required.'
+  },
+
+  /**
+   * Error thrown when a Conversation reference is missing claims.aud.
+   */
+  ConversationInvalidAud: {
+    code: -120750,
+    description: 'Conversation is invalid: claims.aud (agent client ID) is required.'
+  },
+
+  /**
+   * Error thrown when CreateConversationOptionsBuilder.build() is called without any members.
+   */
+  CreateConversationBuilderMembersRequired: {
+    code: -120751,
+    description: 'CreateConversationOptionsBuilder: at least one members entry must be added via withUser().'
+  },
+
+  /**
+   * Error thrown when a proactive operation that requires TurnState load/save is called without app storage.
+   */
+  ProactiveAppStorageRequired: {
+    code: -120752,
+    description: 'This proactive operation requires app storage to load and save TurnState. Set options.storage on AgentApplication.'
+  },
+
   // ============================================================================
   // General Errors (-120990)
   // ============================================================================

package/src/turnContext.ts

@@ -330,7 +330,12 @@ export class TurnContext {
    * @protected
    */
   protected copyTo (context: TurnContext): void {
-    ['_adapter', '_activity', '_respondedRef', '_services', '_onSendActivities', '_onUpdateActivity', '_onDeleteActivity'].forEach((prop: string) => ((context as any)[prop] = (this as any)[prop]))
+    // Skip _streamingResponse: it holds a reference to the HTTP response of the original request.
+    // Copying it to a cloned context would cause the clone to write to an already-completed response.
+    const copyableProperties = Object.keys(this).filter((prop) => prop !== '_streamingResponse')
+    for (const prop of copyableProperties) {
+      ;(context as any)[prop] = (this as any)[prop]
+    }
   }
 
   /**