docs: sequence diagram drift detected

[github-actions]

The weekly verify-sequence-diagrams audit found that one or more Mermaid sequence diagrams under docs/ have drifted from the current implementation. The code is the source of truth; the diagrams are what should be corrected.

Each drifted diagram is described in its own comment below, with the proposed fix as a diff. To correct them all in a single pull request, assign this issue to @copilot (or comment @copilot apply the fixes described in the comments on this issue). The resulting PR should update only the docs/*sequence-diagram.md files named in the comments.

Filed automatically by the verify-sequence-diagrams workflow. The audit is best-effort — verify against the code before merging.

[github-actions]

docs/cloudadapter-sequence-diagram.md

This sequence diagram has drifted from the current implementation and needs to be updated. The code is the source of truth.

What the audit found:

docs/cloudadapter-sequence-diagram.md: Narrowed the blocking-path alt condition from "DeliveryMode == Stream (or ExpectReplies / Invoke)" to "DeliveryMode == Stream" — the SSE/ResponseBegin(text/event-stream) behavior shown in that block is Stream-specific; Invoke/ExpectReplies use a different writer (ExpectRepliesResponseWriter).

Proposed fix (validated as parseable Mermaid before filing):

diff --git a/docs/cloudadapter-sequence-diagram.md b/docs/cloudadapter-sequence-diagram.md
index f04b8ad..19a8bab 100644
--- a/docs/cloudadapter-sequence-diagram.md
+++ b/docs/cloudadapter-sequence-diagram.md
@@ -25,7 +25,7 @@ sequenceDiagram
 
     Client->>CloudAdapter: POST /api/messages
 
-    alt DeliveryMode == Stream (or ExpectReplies / Invoke)
+    alt DeliveryMode == Stream
         Note over CloudAdapter: Blocking path
         CloudAdapter->>ChannelResponseQueue: StartHandlerForRequest(requestId)
         CloudAdapter->>HttpResponse: ResponseBegin()<br/>(Content-Type: text/event-stream)

To apply: edit docs/cloudadapter-sequence-diagram.md so it matches the diff above. Change only this doc file — do not modify anything under src/. Keep the Mermaid syntax valid and preserve the file's UTF-8 BOM.

[github-actions]

docs/full-cloudadapter-sequence-diagram.md

This sequence diagram has drifted from the current implementation and needs to be updated. The code is the source of truth.

What the audit found:

docs/full-cloudadapter-sequence-diagram.md: Same Stream-only fix as above, plus corrected pipeline call chain to AdapterBase.RunPipelineAsync → MiddlewareSet.ReceiveActivityWithStatusAsync, added IActivityTaskQueue participant for the Normal path, fixed CompleteHandlerForRequest caller (CloudAdapter, not ProcessActivityAsync), and minor wording fixes.

Proposed fix (validated as parseable Mermaid before filing):

diff --git a/docs/full-cloudadapter-sequence-diagram.md b/docs/full-cloudadapter-sequence-diagram.md
index f04b8ad..8049528 100644
--- a/docs/full-cloudadapter-sequence-diagram.md
+++ b/docs/full-cloudadapter-sequence-diagram.md
@@ -1,6 +1,6 @@
 # CloudAdapter Pipeline Sequence Diagram
 
-Shows the interaction between `CloudAdapter.ProcessAsync`, the middleware pipeline, `ITurnContext.SendActivity`, and `IAgent` — including both response paths.
+Shows the interaction between `CloudAdapter.ProcessAsync`, the middleware pipeline, `ITurnContext.SendActivityAsync`, and `IAgent` — including both response paths.
 
 ## Response Paths
 
@@ -14,6 +14,7 @@ sequenceDiagram
     participant Client
     participant CloudAdapter
     participant ChannelResponseQueue
+    participant ActivityTaskQueue as IActivityTaskQueue
     participant ProcessActivity as ProcessActivityAsync
     participant MiddlewareSet
     participant Middleware as Middleware[0..N]
@@ -25,7 +26,7 @@ sequenceDiagram
 
     Client->>CloudAdapter: POST /api/messages
 
-    alt DeliveryMode == Stream (or ExpectReplies / Invoke)
+    alt DeliveryMode == Stream
         Note over CloudAdapter: Blocking path
         CloudAdapter->>ChannelResponseQueue: StartHandlerForRequest(requestId)
         CloudAdapter->>HttpResponse: ResponseBegin()<br/>(Content-Type: text/event-stream)
@@ -33,7 +34,8 @@ sequenceDiagram
 
         par Background: agent processing
             ProcessActivity->>TurnContext: new TurnContext(adapter, activity)
-            ProcessActivity->>MiddlewareSet: RunPipelineAsync(context, agent.OnTurnAsync)
+            ProcessActivity->>AdapterBase: RunPipelineAsync(context, agent.OnTurnAsync)
+            AdapterBase->>MiddlewareSet: ReceiveActivityWithStatusAsync(context, agent.OnTurnAsync)
 
             loop Middleware chain (recursive)
                 MiddlewareSet->>Middleware: OnTurnAsync(context, next)
@@ -51,7 +53,7 @@ sequenceDiagram
             AdapterBase->>AdapterBase: HostResponseAsync(incomingActivity, outActivity)
             Note over AdapterBase: DeliveryMode == Stream → returns true
             AdapterBase->>ChannelResponseQueue: SendActivitiesAsync(requestId, activities)
-            ChannelResponseQueue-->>AdapterBase: return true
+            ChannelResponseQueue-->>AdapterBase: activities queued
 
         and HTTP thread: consuming response queue
             CloudAdapter->>ChannelResponseQueue: HandleResponsesAsync(requestId, writer.OnResponse)
@@ -62,19 +64,20 @@ sequenceDiagram
             end
         end
 
-        ProcessActivity-->>ChannelResponseQueue: CompleteHandlerForRequest(requestId)
+        CloudAdapter->>ChannelResponseQueue: CompleteHandlerForRequest(requestId)
         ChannelResponseQueue-->>CloudAdapter: HandleResponsesAsync returns
         CloudAdapter->>HttpResponse: ResponseEnd()<br/>(writes invokeResponse event if Invoke)
-        HttpResponse->>Client: final SSE event / close
+        HttpResponse->>Client: stream close
 
     else DeliveryMode == Normal (default)
         Note over CloudAdapter: Fire-and-forget path
-        CloudAdapter->>CloudAdapter: QueueBackgroundActivity(activity)
+        CloudAdapter->>ActivityTaskQueue: QueueBackgroundActivity(activity)
         CloudAdapter->>Client: 202 Accepted (immediate return)
 
         Note over ProcessActivity: Background worker picks up activity
         ProcessActivity->>TurnContext: new TurnContext(adapter, activity)
-        ProcessActivity->>MiddlewareSet: RunPipelineAsync(context, agent.OnTurnAsync)
+        ProcessActivity->>AdapterBase: RunPipelineAsync(context, agent.OnTurnAsync)
+        AdapterBase->>MiddlewareSet: ReceiveActivityWithStatusAsync(context, agent.OnTurnAsync)
 
         loop Middleware chain (recursive)
             MiddlewareSet->>Middleware: OnTurnAsync(context, next)
@@ -111,4 +114,4 @@ In the Stream path, `ChannelResponseQueue` acts as a thread-safe bridge between
 
 - **Producer**: background agent thread calls `SendActivitiesAsync()` → writes activities to an unbounded `Channel<IActivity>`
 - **Consumer**: HTTP request thread calls `HandleResponsesAsync()` → reads activities and passes them to `ActivityResponseHandler.OnResponse()`, which writes SSE events to `HttpResponse.Body`
-- **Completion**: when `ProcessActivityAsync` finishes, it calls `CompleteHandlerForRequest()` → closes the channel writer → consumer loop exits → `ResponseEnd()` is called
+- **Completion**: when `ProcessActivityAsync` finishes, `CloudAdapter` calls `CompleteHandlerForRequest()` → closes the channel writer → consumer loop exits → `ResponseEnd()` is called

To apply: edit docs/full-cloudadapter-sequence-diagram.md so it matches the diff above. Change only this doc file — do not modify anything under src/. Keep the Mermaid syntax valid and preserve the file's UTF-8 BOM.

[github-actions]

docs/oauth-internal-sequence-diagram.md

This sequence diagram has drifted from the current implementation and needs to be updated. The code is the source of truth.

What the audit found:

docs/oauth-internal-sequence-diagram.md: Removed IsValidActivity() steps that are short-circuited when forceSignIn=true; fixed the error branch (no _userSignInFailureHandler, adds ResetStateAsync); corrected GetTurnTokenAsync caching/refresh conditions (agentic-request case); fixed SignInState storage key to oauth/{channelId}/{userId}/userAuthorizationState; corrected timeout invoke-response behavior.

Proposed fix (validated as parseable Mermaid before filing):

diff --git a/docs/oauth-internal-sequence-diagram.md b/docs/oauth-internal-sequence-diagram.md
index 336282f..c4bab46 100644
--- a/docs/oauth-internal-sequence-diagram.md
+++ b/docs/oauth-internal-sequence-diagram.md
@@ -37,7 +37,6 @@ sequenceDiagram
     Disp->>ABUA: SignInUserAsync(context, forceSignIn=true)
     activate ABUA
 
-    ABUA->>ABUA: IsValidActivity() → true (Message)
     ABUA->>ABUA: GetFlowStateAsync()
     ABUA->>Storage: ReadAsync(["oauth/{name}/{channel}/{conv}/flowState"])
     Storage-->>ABUA: FlowState { FlowStarted=false }
@@ -99,7 +98,6 @@ sequenceDiagram
     Disp->>ABUA: SignInUserAsync(context, forceSignIn=true)
     activate ABUA
 
-    ABUA->>ABUA: IsValidActivity() → true
     ABUA->>Storage: ReadAsync(flowState key)
     Storage-->>ABUA: FlowState { FlowStarted=false }
 
@@ -216,8 +214,9 @@ sequenceDiagram
     else Error
         ABUA->>ABUA: throws
         Disp-->>UA: SignInResponse { Status=Error, Cause }
+        UA->>Disp: ResetStateAsync(context, handlerName)
         UA->>UA: DeleteSignInStateAsync()
-        UA->>UA: Call _userSignInFailureHandler
+        Note over UA: Invoke turn — no _userSignInFailureHandler
         UA-->>App: false
     end
     deactivate ABUA
@@ -276,9 +275,9 @@ sequenceDiagram
     activate UA
     UA->>UA: Find cached HandlerToken
 
-    alt Token not expired & not exchangeable
+    alt Token not expired & not exchangeable & not agentic request
         UA-->>Agent: token.Token
-    else Token expired or exchangeable
+    else Token expired, exchangeable, or agentic request
         UA->>Disp: Get(handlerName)
         Disp-->>UA: IUserAuthorization instance
         UA->>ABUA: GetRefreshedUserTokenAsync(context, exchangeConn, scopes)
@@ -290,7 +289,7 @@ sequenceDiagram
         ABUA->>ABUA: HandleOBO(context, token, ...)
         ABUA-->>UA: TokenResponse (refreshed/exchanged)
         deactivate ABUA
-        UA->>UA: CacheToken(handlerName, response)
+        UA->>UA: CacheToken(handlerName, response) [if prior token not exchangeable]
         UA-->>Agent: response.Token
     end
     deactivate UA
@@ -312,13 +311,13 @@ sequenceDiagram
 ## Storage Keys
 
 - **FlowState**: `oauth/{handlerName}/{channelId}/{conversationId}/flowState`
-- **SignInState**: Managed by `UserAuthorization` via `ITurnState` (conversation-scoped)
+- **SignInState**: `oauth/{channelId}/{userId}/userAuthorizationState` (managed by `UserAuthorization` via `IStorage`)
 
 ## Important Behaviors
 
 - **AutoSignIn**: If enabled (default), `StartOrContinueSignInUserAsync` is called every turn before route matching. If the user has a cached token, this is a fast path (single Token Service call).
 - **Continuation Activity**: When a multi-turn flow starts, the original user message is banked. After sign-in completes on a different turn (Invoke), the banked activity is replayed via `ProcessProactiveAsync`.
 - **Invoke Response Codes**: `200` = success, `412` = consent required (Teams retries with consent), `400` = critical failure (Teams stops), `404` = invalid magic code, `500` = retriable error.
-- **Timeout**: `OAuthSettings.Timeout` (default from `OAuthSettings.DefaultTimeoutValue`). After expiry, all invokes return errors.
+- **Timeout**: `OAuthSettings.Timeout` (default from `OAuthSettings.DefaultTimeoutValue`). After expiry, `signin/tokenExchange` invokes return `400`; other invokes return `200` with no body.
 - **InvalidSignInRetryMax**: Non-tokenExchange continuations (e.g., bad magic codes) are retried up to this limit before throwing `AuthExceptionReason.InvalidSignIn`.
 - **OBO**: Performed after every successful token acquisition (BeginFlow cached token, ContinueFlow token, GetRefreshedUserToken). Uses `IConnections` to resolve an `IOBOExchange` provider.

To apply: edit docs/oauth-internal-sequence-diagram.md so it matches the diff above. Change only this doc file — do not modify anything under src/. Keep the Mermaid syntax valid and preserve the file's UTF-8 BOM.

[github-actions]

docs/proactive-sequence-diagram.md

This sequence diagram has drifted from the current implementation and needs to be updated. The code is the source of truth.

What the audit found:

docs/proactive-sequence-diagram.md: Corrected note attributing state load/save to Proactive.OnTurnAsync wrapping ProcessProactiveAsync, not the adapter call alone.

Proposed fix (validated as parseable Mermaid before filing):

diff --git a/docs/proactive-sequence-diagram.md b/docs/proactive-sequence-diagram.md
index a09a0c7..958c1d5 100644
--- a/docs/proactive-sequence-diagram.md
+++ b/docs/proactive-sequence-diagram.md
@@ -208,7 +208,7 @@ sequenceDiagram
 
 - **Conversation** — A record containing `ConversationReference` + `Claims` (JWT claims for identity reconstruction). Serializable for storage.
 - **ConversationBuilder** — Fluent builder for manually constructing `Conversation` instances without an existing `ITurnContext`.
-- **ProcessProactiveAsync** vs **ContinueConversationAsync** — `ProcessProactiveAsync` creates a full turn pipeline (middleware, state); `ContinueConversationAsync` (on adapter) is simpler and only provides a TurnContext callback.
+- **ProcessProactiveAsync** vs **ContinueConversationAsync** — `Proactive.ContinueConversationAsync` uses `ProcessProactiveAsync` plus `OnTurnAsync` to create a full turn pipeline (middleware, state); `ContinueConversationAsync` (on adapter) is simpler and only provides a TurnContext callback.
 - **Token Handling** — `[ContinueConversation(autoSignInHandlers: "me")]` automatically retrieves user tokens during proactive turns. If the user hasn't signed in, `UserNotSignedIn` is thrown.
 - **Exception Capture** — Exceptions inside the proactive callback are captured via `ExceptionDispatchInfo` and re-thrown after the adapter completes, since they would otherwise be lost.
 - **Query Parameters** — HTTP continue endpoints pass query string values as `Activity.Value` with `ValueType = "application/vnd.microsoft.activity.continueconversation+json"`.

To apply: edit docs/proactive-sequence-diagram.md so it matches the diff above. Change only this doc file — do not modify anything under src/. Keep the Mermaid syntax valid and preserve the file's UTF-8 BOM.

[github-actions]

docs/serialization-extension-sequence-diagram.md

This sequence diagram has drifted from the current implementation and needs to be updated. The code is the source of truth.

What the audit found:

docs/serialization-extension-sequence-diagram.md: Replaced a non-existent Teams converter example with the real SharePoint converters (AceDataConverter, AceRequestConverter).

Proposed fix (validated as parseable Mermaid before filing):

diff --git a/docs/serialization-extension-sequence-diagram.md b/docs/serialization-extension-sequence-diagram.md
index c656b0a..8e5eba7 100644
--- a/docs/serialization-extension-sequence-diagram.md
+++ b/docs/serialization-extension-sequence-diagram.md
@@ -102,7 +102,7 @@ sequenceDiagram
 
 ## Developer Usage Examples
 
-### Adding Custom Converters (e.g., Teams extension)
+### Adding Custom Converters (e.g., SharePoint extension)
 
 ```csharp
 [SerializationInit]
@@ -112,8 +112,8 @@ internal class SerializationInit
     {
         var converters = new List<JsonConverter>
         {
-            new TeamsChannelDataConverter(),
-            new SurfaceConverter()
+            new AceDataConverter(),
+            new AceRequestConverter()
         };
         ProtocolJsonSerializer.ApplyExtensionConverters(converters);
     }

To apply: edit docs/serialization-extension-sequence-diagram.md so it matches the diff above. Change only this doc file — do not modify anything under src/. Keep the Mermaid syntax valid and preserve the file's UTF-8 BOM.

[github-actions]

docs/streaming-response-sequence-diagram.md

This sequence diagram has drifted from the current implementation and needs to be updated. The code is the source of truth.

What the audit found:

docs/streaming-response-sequence-diagram.md: Replaced incorrect "A2A/Agent-to-Agent" labels with the canonical DeliveryModes.Stream SSE term.

Proposed fix (validated as parseable Mermaid before filing):

diff --git a/docs/streaming-response-sequence-diagram.md b/docs/streaming-response-sequence-diagram.md
index a4401df..b9d07b1 100644
--- a/docs/streaming-response-sequence-diagram.md
+++ b/docs/streaming-response-sequence-diagram.md
@@ -8,7 +8,7 @@ Shows how `StreamingResponse` delivers chunked intermediate messages on a timer
 - **TurnContext** — Per-turn context; exposes `StreamingResponse` property.
 - **StreamingResponse** — SDK-provided chunked message delivery (internal class).
 - **Timer** — Internal `System.Threading.Timer` that fires at `Interval` ms.
-- **Channel** — The upstream channel (Teams, WebChat, DirectLine, or Agent-to-Agent via SSE).
+- **Channel** — The upstream channel (Teams, WebChat, DirectLine, or DeliveryModes.Stream SSE).
 
 ## Channel Defaults
 
@@ -16,7 +16,7 @@ Shows how `StreamingResponse` delivers chunked intermediate messages on a timer
 |---------|----------|----------|-------|
 | Teams | 1000ms | Assigned by first response | MUST use Activity.Id from first send |
 | WebChat / DirectLine | 500ms | Random GUID | |
-| DeliveryMode.Stream (A2A) | 100ms | Random GUID | |
+| DeliveryModes.Stream SSE | 100ms | Random GUID | |
 | Other / ExpectReplies | N/A | N/A | Non-streaming; buffers text, sends single final message |
 
 ## Streaming Channel Flow
@@ -143,7 +143,7 @@ sequenceDiagram
 - **Timer is one-shot, re-armed after each send** — prevents overlapping sends if `SendActivityAsync` takes longer than `Interval` (e.g., MSAL token refresh).
 - **InitialDelay** (default 250ms) — used for the first `QueueTextChunk` if no informative was sent, enabling faster stream start.
 - **Message accumulates** — each intermediate message sends the FULL text so far (not a delta). Channel displays latest as replacement.
-- **StreamId** — Teams assigns it from first response; WebChat/DirectLine/A2A uses a pre-generated GUID set on every outgoing `Activity.Id`.
+- **StreamId** — Teams assigns it from first response; WebChat/DirectLine/DeliveryModes.Stream SSE uses a pre-generated GUID set on every outgoing `Activity.Id`.
 - **EndStreamTimeout** — defaults to 2 minutes. If queue doesn't drain in time, returns `Timeout`.
 - **ResetAsync** — allows reusing `StreamingResponse` for multiple streams in the same turn (waits for current stream to end first).
 

To apply: edit docs/streaming-response-sequence-diagram.md so it matches the diff above. Change only this doc file — do not modify anything under src/. Keep the Mermaid syntax valid and preserve the file's UTF-8 BOM.

[github-actions]

docs/teams-sso-sequence-diagram.md

This sequence diagram has drifted from the current implementation and needs to be updated. The code is the source of truth.

What the audit found:

docs/teams-sso-sequence-diagram.md: Fixed ConsentRequired flow to show a second signin/tokenExchange invoke (not verifyState/magic code) with ExchangeToken(); removed nonexistent UserSignInFailureHandler step on exchange failure; corrected UserAuthorization source path to App/UserAuth/UserAuthorization.cs.

Proposed fix (validated as parseable Mermaid before filing):

diff --git a/docs/teams-sso-sequence-diagram.md b/docs/teams-sso-sequence-diagram.md
index 39e26ed..6769abd 100644
--- a/docs/teams-sso-sequence-diagram.md
+++ b/docs/teams-sso-sequence-diagram.md
@@ -121,7 +121,7 @@ sequenceDiagram
 ```
 
 ## SignIn, ConsentRequired
-This represents the signin flow where Teams SSO token exchange fails because the user hasn't consented. Teams prompts for consent, then sends a verifyState invoke with a magic code. If OBO is configured, the OBO is performed on the token returned by the Token Service (in `Turn 3`) prior to setting the Turn Token. Note that `Turn 4` is the same flow as `SignedIn` above.
+This represents the signin flow where Teams SSO token exchange fails because the user hasn't consented. Teams prompts for consent, then sends another tokenExchange invoke with a post-consent token. If OBO is configured, the OBO is performed on the token returned by the Token Service (in `Turn 3`) prior to setting the Turn Token. Note that `Turn 4` is the same flow as `SignedIn` above.
 
 ```mermaid
 sequenceDiagram
@@ -173,11 +173,11 @@ sequenceDiagram
     %% turn 3
     rect rgba(170, 128, 128, .1)
     Note over Teams, Agent: Turn 3 (invoke)
-    Teams->>AgentApplication: Invoke(signin/verifyState)
+    Teams->>AgentApplication: Invoke(signin/tokenExchange)
     activate AgentApplication
     AgentApplication->>UserAuthorization: SignIn (continuation)
     activate UserAuthorization
-    UserAuthorization->>TokenService: GetUserToken(code)
+    UserAuthorization->>TokenService: ExchangeToken()
     activate TokenService
     TokenService-->>UserAuthorization: TokenResponse (200)
     deactivate TokenService
@@ -258,11 +258,7 @@ sequenceDiagram
     TokenService-->>UserAuthorization: ErrorResponse (non-consent error)
     deactivate TokenService
     UserAuthorization->>UserAuthorization: Delete FlowState
-    UserAuthorization->>Agent: UserSignInFailureHandler
-    activate Agent
-    Agent->>Teams: Activity Error Response
-    deactivate Agent
-    UserAuthorization-->>AgentApplication: SignIn (complete)
+    UserAuthorization-->>AgentApplication: SignIn (error)
     deactivate UserAuthorization
     AgentApplication-->>Teams: InvokeResponse:400 (turn ends)
     deactivate AgentApplication
@@ -273,8 +269,7 @@ sequenceDiagram
 
 | Component | Path |
 |-----------|------|
-| UserAuthorization | `src/libraries/Builder/Microsoft.Agents.Builder/UserAuth/` |
+| UserAuthorization | `src/libraries/Builder/Microsoft.Agents.Builder/App/UserAuth/UserAuthorization.cs` |
 | Authentication.Msal | `src/libraries/Authentication/Authentication.Msal/` |
 | Token Service Client | `src/libraries/Client/Microsoft.Agents.Connector/` |
 | AgentApplication (SignIn orchestration) | `src/libraries/Builder/Microsoft.Agents.Builder/App/AgentApplication.cs` |
-

To apply: edit docs/teams-sso-sequence-diagram.md so it matches the diff above. Change only this doc file — do not modify anything under src/. Keep the Mermaid syntax valid and preserve the file's UTF-8 BOM.