@sendbird/ai-agent-messenger-react 1.40.1 → 1.42.0

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import type { AIAgentModule } from '@sendbird/chat/aiAgent';
 import { AriaRole } from 'react';
 import type { BaseChannelCollectionEventHandler } from '@sendbird/chat/groupChannel';
 import type { BaseMessage } from '@sendbird/chat/message';
+import type { CollectionEventSource } from '@sendbird/chat';
 import { ComponentType } from 'react';
 import { Context } from 'react';
 import type { Conversation as Conversation_2 } from '@sendbird/chat/aiAgent';
@@ -64,8 +65,11 @@ declare interface ActiveChannelUpdatedParams {
 }
 
 export declare interface AgentClientHandlers extends AIAgentClientHandlers {
+    /** @internal */
     onMessageSend?: (message: string) => void;
+    /** @internal */
     onFunctionCallDetailClick?: (func: FunctionCallsInfo) => void;
+    /** @internal */
     onInitializeFailed?: (error: Error) => void;
 }
 
@@ -250,8 +254,7 @@ customApiHost?: string;
 * */
 agentPreviewConfigs?: AgentPreviewConfigs;
 /**
-* @internal
-* @description Event handlers for the ai agent client.
+* @public
 */
 handlers?: AgentClientHandlers;
 /**
@@ -266,7 +269,8 @@ enableCloseConversationButton?: boolean;
 enableExpandButton?: boolean;
 /**
 * @internal
-* @description Whether to automatically disconnect the WebSocket when the user is inactive in launcher mode.
+* @description Whether to automatically disconnect the WebSocket after the messenger stays closed for 60 seconds.
+* The legacy name is kept for compatibility; this applies regardless of launcher rendering or customization.
 * Set to false to keep the connection alive even during inactivity. (default: true)
 */
 enableAutoDisconnectInLauncher?: boolean;
@@ -306,6 +310,11 @@ declare abstract class AIAgentBaseStats {
     protected abstract buildPayload(): AIAgentStatPayload | null;
     protected abstract getMetricKey(): string;
 
+    /** The stat type this metric is collected under; assertion metrics override it. */
+    protected getStatType(): string {
+        return AI_AGENT_STAT_TYPE;
+    }
+
     setCommitCallback(callback: StatsAppendCallback): this {
         this.commitCallback = callback;
         return this;
@@ -402,7 +411,7 @@ declare abstract class AIAgentBaseStats {
         if (!payload) return false;
 
         this.committed = true;
-        return this.commitCallback(AI_AGENT_STAT_TYPE, payload);
+        return this.commitCallback(this.getStatType(), payload);
     }
 }
 
@@ -433,6 +442,10 @@ declare interface AIAgentClientHandlers {
      * should be efficient and non-blocking, as this may be called frequently.
      */
     onLiveMetric?: (metric: LiveMetric) => void;
+    /**
+     * Called when a displayable nudge message is received after `requestNudgeMessage`.
+     */
+    onNudgeMessageReceived?: (response: NudgeMessageResponse) => void;
 }
 
 declare type AIAgentCommonIconName =
@@ -636,7 +649,15 @@ declare interface AIAgentConversationContextValue {
         input: InputState;
     };
 
+    // TODO: fold into `_stats.enabled`.
     _statsEnabled: boolean;
+    /** @internal What the platform packages report to the stats trackers. */
+    _stats: {
+        /** A message row's reveal animation starting. */
+        onMessageLifecycleAnimationStart: (messageId: number) => void;
+        /** A message row's reveal animation stopping, and whether it revealed everything. */
+        onMessageLifecycleAnimationComplete: (messageId: number, completed: boolean) => void;
+    };
 }
 
 declare interface AIAgentConversationListContextValue {
@@ -1002,8 +1023,7 @@ export declare type AIAgentProps = PropsWithChildren<{
      * */
     agentPreviewConfigs?: AgentPreviewConfigs;
     /**
-     * @internal
-     * @description Event handlers for the ai agent client.
+     * @public
      */
     handlers?: AgentClientHandlers;
     /**
@@ -1018,7 +1038,8 @@ export declare type AIAgentProps = PropsWithChildren<{
     enableExpandButton?: boolean;
     /**
      * @internal
-     * @description Whether to automatically disconnect the WebSocket when the user is inactive in launcher mode.
+     * @description Whether to automatically disconnect the WebSocket after the messenger stays closed for 60 seconds.
+     * The legacy name is kept for compatibility; this applies regardless of launcher rendering or customization.
      * Set to false to keep the connection alive even during inactivity. (default: true)
      */
     enableAutoDisconnectInLauncher?: boolean;
@@ -1142,6 +1163,9 @@ declare type AIAgentStatsTrackerCollection = {
     streamStalled: StreamStalledStatsTracker;
     typingIndicatorAbsentTimeout: TypingIndicatorAbsentTimeoutStatsTracker;
     renderedContentUnusable: RenderedContentUnusableStatsTracker;
+    streamingMessageValidation: StreamingMessageValidationStatsTracker;
+    duplicateMessageResponse: DuplicateMessageResponseStatsTracker;
+    messageLifecycleEvent: MessageLifecycleEventStatsTracker;
 };
 
 declare type AIAgentStatsTrackers = AIAgentStatsTrackerCollection & {
@@ -1492,6 +1516,8 @@ declare type ChatSDKBaseChannelCollectionEventHandler = BaseChannelCollectionEve
 
 declare type ChatSDKBaseMessage = BaseMessage;
 
+declare type ChatSDKCollectionEventSource = CollectionEventSource;
+
 declare type ChatSDKConversation = Conversation_2;
 
 declare type ChatSDKConversationStatus = ConversationStatus;
@@ -2975,6 +3001,86 @@ declare interface Dispatcher {
     ): void;
 }
 
+/**
+ * Spec: duplicate_message_response
+ *
+ * Detects the AI giving the same answer text twice: either as two bubbles in a row, or once
+ * per turn with the user asking again in between. The point is to size how often it happens,
+ * not to suppress it.
+ *
+ * Timeline:
+ * - Whenever the conversation changes, the latest settled reply is compared with the reply
+ *   before it. Anyone other than the agent is stepped over, so a turn in between does not
+ *   separate the two. A reply that cannot be compared — still streaming, or with no text —
+ *   does end the run, because it sits between them as an answer that was given.
+ *
+ * Payload:
+ * - value: empty; the pair is the whole observation.
+ * - extra.prev_message_id / extra.next_message_id: the two replies that matched.
+ *
+ * Policy:
+ * - A reply that already reported a duplicate never reports one again, which is what keeps the
+ *   tail from being counted again every time it is re-read. That memory lives only for the
+ *   session: a duplicate is rare enough, and rarely still the last two replies on a later
+ *   visit, for a repeat count to matter.
+ * - Runs of three or more are not modelled; each settled reply looks back exactly one reply.
+ * - Only succeeded messages are read, because the list pins unsent ones past everything else.
+ */
+declare class DuplicateMessageResponseStatsTracker extends StatsTrackerBase {
+    private readonly emittedMessageChannels = new Map<number, string>();
+
+    onMessagesChanged(params: ObservedConversation): void {
+        const replies = this.findLastTwoReplies(params.messages, params.aiAgentUserId);
+        if (!replies) return;
+        if (replies.previous.message !== replies.latest.message) return;
+        if (this.emittedMessageChannels.has(replies.latest.messageId)) return;
+
+        this.emit(replies.latest, replies.previous, params);
+    }
+
+    clear(): void {
+        this.emittedMessageChannels.clear();
+    }
+
+    private findLastTwoReplies(
+    messages: ChatSDKBaseMessage[],
+    aiAgentUserId: string,
+    ): { latest: ChatSDKBaseMessage; previous: ChatSDKBaseMessage } | null {
+        let latest: ChatSDKBaseMessage | null = null;
+        let previous: ChatSDKBaseMessage | null = null;
+
+        forEachMessageNewestFirst(messages, (message) => {
+            // Both list comparators pin an unsent message past every succeeded one, so its position
+            // says nothing about when it was sent: it can neither end a run nor be compared.
+            if (isSendableMessage(message) && message.sendingStatus !== SendingStatus.SUCCEEDED) return;
+            // Anyone other than the agent is stepped over: answering two separate turns with the same
+            // text is the same defect as answering one turn twice.
+            if (!isSentBy(message, aiAgentUserId)) return;
+            // A reply that cannot be compared sits between the two, so they are not adjacent either.
+            if (!isComparableReply(message, aiAgentUserId)) return 'stop';
+
+            if (!latest) latest = message;
+            else {
+                previous = message;
+                return 'stop';
+            }
+        });
+
+        return latest && previous ? { latest, previous } : null;
+    }
+
+    private emit(latest: ChatSDKBaseMessage, previous: ChatSDKBaseMessage, params: ObservedConversation): void {
+        evictOldestIfAtLimit(this.emittedMessageChannels, DUPLICATE_MESSAGE_RESPONSE_EMITTED_LIMIT);
+        this.emittedMessageChannels.set(latest.messageId, params.channelUrl);
+
+        new DuplicateMessageResponseStats()
+        .setDuplicatePair({ previousMessageId: previous.messageId, nextMessageId: latest.messageId })
+        .setConversationId(params.conversationId)
+        .setCommitCallback(this.commitCallback)
+        .commit();
+    }
+}
+
 declare enum DurationKey {
     ACK_TO_FIRST_CHUNK = 'ack_to_first_chunk_ms',
     AFTER_TPEN_ABSENT = 'after_tpen_absent_ms',
@@ -3093,8 +3199,17 @@ export declare interface FeedbackInfo {
     comment?: string;
 }
 
+export declare interface FixedLauncherProps extends Pick<LauncherProps, 'opened' | 'setOpened' | 'entryPoint' | 'activeRoute'> {
+    /** Configured launcher size, available for sizing or positioning your custom UI. */
+    size?: number;
+    /** Placement styles for the custom launcher. Apply them or use your own positioning. */
+    style?: CSSProperties;
+}
+
 export declare const FixedMessenger: ForwardRefExoticComponent<MessengerProps & RefAttributes<MessengerSessionRef>> & {
     Style: (props: FixedMessengerStyleProps) => null;
+    Launcher: ({ component }: FixedMessengerLauncherProps) => null;
+    NudgeMessage: ({ component }: FixedMessengerNudgeMessageProps) => null;
     Conversation: ({ component }: FixedMessengerConversationProps) => null;
     ConversationChildren: ({ children }: PropsWithChildren) => null;
     ConversationList: ({ component }: FixedMessengerConversationListProps) => null;
@@ -3109,6 +3224,10 @@ declare interface FixedMessengerConversationProps {
     component: ComponentType<ConversationProps>;
 }
 
+declare interface FixedMessengerLauncherProps {
+    component: ComponentType<FixedLauncherProps>;
+}
+
 export declare type FixedMessengerMargin = {
     top: number;
     bottom: number;
@@ -3116,6 +3235,10 @@ export declare type FixedMessengerMargin = {
     end: number;
 };
 
+declare interface FixedMessengerNudgeMessageProps {
+    component: ComponentType<FixedNudgeMessageProps>;
+}
+
 export declare type FixedMessengerPosition = `${PositionHorizontal}-${PositionVertical}`;
 
 declare interface FixedMessengerStyleProps {
@@ -3138,6 +3261,11 @@ declare interface FixedMessengerStyleProps {
     launcherSize?: number;
 }
 
+export declare interface FixedNudgeMessageProps extends Omit<NudgeMessageViewProps, 'nudgeMessageKey'> {
+    /** Placement styles for the custom nudge message. Apply them or use your own positioning. */
+    style?: CSSProperties;
+}
+
 declare type ForegroundTaskScheduler = (start: () => void) => void | (() => void);
 
 declare interface Form {
@@ -3184,6 +3312,21 @@ export declare interface GroundednessInfo {
     preview_title: string;
 }
 
+declare type GroupChannelMessagesCollectionEvent =
+| {
+    kind: 'initialized';
+    source: 'cache' | 'api';
+    channelUrl: string;
+    messages: ChatSDKBaseMessage[];
+    error?: Error | null;
+}
+| {
+    kind: 'messagesAdded' | 'messagesUpdated' | 'messagesDeleted';
+    source: ChatSDKCollectionEventSource;
+    channelUrl: string;
+    messages: ChatSDKBaseMessage[];
+};
+
 declare interface HeaderTitleProps {
     /** Overrides the default title, which is derived from the channel (AI agent nickname or channel name). */
     title?: string;
@@ -3241,7 +3384,8 @@ BaseMessageProps<{
     onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
-    onStreamAnimationComplete?: () => void;
+    /** `completed` is false when the row went away before the text was fully revealed. */
+    onStreamAnimationComplete?: (params: { completed: boolean }) => void;
     /**
      * Fired (layout effect) when this row starts/stops holding its text — the stream animation is
      * running but nothing is visible yet. The row renders nothing while holding, so the list draws its
@@ -3341,7 +3485,9 @@ export declare const IncomingMessageLayout: {
                 onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
                 onStreamAnimationStart?: () => void;
                 onStreamAnimationProgress?: () => void;
-                onStreamAnimationComplete?: () => void;
+                onStreamAnimationComplete?: (params: {
+                    completed: boolean;
+                }) => void;
                 onStreamAnimationHoldChange?: (holding: boolean) => void;
                 messageTemplateErrorFallback?: ReactNode;
                 messageTemplateLoadingFallback?: ReactNode;
@@ -3424,7 +3570,9 @@ export declare const IncomingMessageLayout: {
                 onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
                 onStreamAnimationStart?: () => void;
                 onStreamAnimationProgress?: () => void;
-                onStreamAnimationComplete?: () => void;
+                onStreamAnimationComplete?: (params: {
+                    completed: boolean;
+                }) => void;
                 onStreamAnimationHoldChange?: (holding: boolean) => void;
                 messageTemplateErrorFallback?: ReactNode;
                 messageTemplateLoadingFallback?: ReactNode;
@@ -3507,7 +3655,9 @@ export declare const IncomingMessageLayout: {
                 onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
                 onStreamAnimationStart?: () => void;
                 onStreamAnimationProgress?: () => void;
-                onStreamAnimationComplete?: () => void;
+                onStreamAnimationComplete?: (params: {
+                    completed: boolean;
+                }) => void;
                 onStreamAnimationHoldChange?: (holding: boolean) => void;
                 messageTemplateErrorFallback?: ReactNode;
                 messageTemplateLoadingFallback?: ReactNode;
@@ -3586,7 +3736,9 @@ export declare const IncomingMessageLayout: {
                 onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
                 onStreamAnimationStart?: () => void;
                 onStreamAnimationProgress?: () => void;
-                onStreamAnimationComplete?: () => void;
+                onStreamAnimationComplete?: (params: {
+                    completed: boolean;
+                }) => void;
                 onStreamAnimationHoldChange?: (holding: boolean) => void;
                 messageTemplateErrorFallback?: ReactNode;
                 messageTemplateLoadingFallback?: ReactNode;
@@ -3669,7 +3821,9 @@ export declare const IncomingMessageLayout: {
                 onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
                 onStreamAnimationStart?: () => void;
                 onStreamAnimationProgress?: () => void;
-                onStreamAnimationComplete?: () => void;
+                onStreamAnimationComplete?: (params: {
+                    completed: boolean;
+                }) => void;
                 onStreamAnimationHoldChange?: (holding: boolean) => void;
                 messageTemplateErrorFallback?: ReactNode;
                 messageTemplateLoadingFallback?: ReactNode;
@@ -3752,7 +3906,9 @@ export declare const IncomingMessageLayout: {
                 onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
                 onStreamAnimationStart?: () => void;
                 onStreamAnimationProgress?: () => void;
-                onStreamAnimationComplete?: () => void;
+                onStreamAnimationComplete?: (params: {
+                    completed: boolean;
+                }) => void;
                 onStreamAnimationHoldChange?: (holding: boolean) => void;
                 messageTemplateErrorFallback?: ReactNode;
                 messageTemplateLoadingFallback?: ReactNode;
@@ -3864,7 +4020,9 @@ export declare const IncomingMessageLayout: {
     onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
-    onStreamAnimationComplete?: () => void;
+    onStreamAnimationComplete?: (params: {
+    completed: boolean;
+    }) => void;
     onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
@@ -3947,7 +4105,9 @@ export declare const IncomingMessageLayout: {
     onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
-    onStreamAnimationComplete?: () => void;
+    onStreamAnimationComplete?: (params: {
+    completed: boolean;
+    }) => void;
     onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
@@ -4030,7 +4190,9 @@ export declare const IncomingMessageLayout: {
     onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
-    onStreamAnimationComplete?: () => void;
+    onStreamAnimationComplete?: (params: {
+    completed: boolean;
+    }) => void;
     onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
@@ -4109,7 +4271,9 @@ export declare const IncomingMessageLayout: {
     onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
-    onStreamAnimationComplete?: () => void;
+    onStreamAnimationComplete?: (params: {
+    completed: boolean;
+    }) => void;
     onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
@@ -4192,7 +4356,9 @@ export declare const IncomingMessageLayout: {
     onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
-    onStreamAnimationComplete?: () => void;
+    onStreamAnimationComplete?: (params: {
+    completed: boolean;
+    }) => void;
     onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
@@ -4275,7 +4441,9 @@ export declare const IncomingMessageLayout: {
     onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
-    onStreamAnimationComplete?: () => void;
+    onStreamAnimationComplete?: (params: {
+    completed: boolean;
+    }) => void;
     onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
@@ -4382,7 +4550,9 @@ export declare const IncomingMessageLayout: {
     onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
-    onStreamAnimationComplete?: () => void;
+    onStreamAnimationComplete?: (params: {
+    completed: boolean;
+    }) => void;
     onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
@@ -4465,7 +4635,9 @@ export declare const IncomingMessageLayout: {
     onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
-    onStreamAnimationComplete?: () => void;
+    onStreamAnimationComplete?: (params: {
+    completed: boolean;
+    }) => void;
     onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
@@ -4548,7 +4720,9 @@ export declare const IncomingMessageLayout: {
     onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
-    onStreamAnimationComplete?: () => void;
+    onStreamAnimationComplete?: (params: {
+    completed: boolean;
+    }) => void;
     onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
@@ -4627,7 +4801,9 @@ export declare const IncomingMessageLayout: {
     onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
-    onStreamAnimationComplete?: () => void;
+    onStreamAnimationComplete?: (params: {
+    completed: boolean;
+    }) => void;
     onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
@@ -4710,7 +4886,9 @@ export declare const IncomingMessageLayout: {
     onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
-    onStreamAnimationComplete?: () => void;
+    onStreamAnimationComplete?: (params: {
+    completed: boolean;
+    }) => void;
     onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
@@ -4793,7 +4971,9 @@ export declare const IncomingMessageLayout: {
     onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
-    onStreamAnimationComplete?: () => void;
+    onStreamAnimationComplete?: (params: {
+    completed: boolean;
+    }) => void;
     onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
@@ -4923,7 +5103,9 @@ export declare const IncomingMessageLayout: {
             onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
             onStreamAnimationStart?: () => void;
             onStreamAnimationProgress?: () => void;
-            onStreamAnimationComplete?: () => void;
+            onStreamAnimationComplete?: (params: {
+                completed: boolean;
+            }) => void;
             onStreamAnimationHoldChange?: (holding: boolean) => void;
             messageTemplateErrorFallback?: ReactNode;
             messageTemplateLoadingFallback?: ReactNode;
@@ -5006,7 +5188,9 @@ export declare const IncomingMessageLayout: {
             onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
             onStreamAnimationStart?: () => void;
             onStreamAnimationProgress?: () => void;
-            onStreamAnimationComplete?: () => void;
+            onStreamAnimationComplete?: (params: {
+                completed: boolean;
+            }) => void;
             onStreamAnimationHoldChange?: (holding: boolean) => void;
             messageTemplateErrorFallback?: ReactNode;
             messageTemplateLoadingFallback?: ReactNode;
@@ -5089,7 +5273,9 @@ export declare const IncomingMessageLayout: {
             onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
             onStreamAnimationStart?: () => void;
             onStreamAnimationProgress?: () => void;
-            onStreamAnimationComplete?: () => void;
+            onStreamAnimationComplete?: (params: {
+                completed: boolean;
+            }) => void;
             onStreamAnimationHoldChange?: (holding: boolean) => void;
             messageTemplateErrorFallback?: ReactNode;
             messageTemplateLoadingFallback?: ReactNode;
@@ -5170,7 +5356,9 @@ export declare const IncomingMessageLayout: {
             onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
             onStreamAnimationStart?: () => void;
             onStreamAnimationProgress?: () => void;
-            onStreamAnimationComplete?: () => void;
+            onStreamAnimationComplete?: (params: {
+                completed: boolean;
+            }) => void;
             onStreamAnimationHoldChange?: (holding: boolean) => void;
             messageTemplateErrorFallback?: ReactNode;
             messageTemplateLoadingFallback?: ReactNode;
@@ -5253,7 +5441,9 @@ export declare const IncomingMessageLayout: {
             onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
             onStreamAnimationStart?: () => void;
             onStreamAnimationProgress?: () => void;
-            onStreamAnimationComplete?: () => void;
+            onStreamAnimationComplete?: (params: {
+                completed: boolean;
+            }) => void;
             onStreamAnimationHoldChange?: (holding: boolean) => void;
             messageTemplateErrorFallback?: ReactNode;
             messageTemplateLoadingFallback?: ReactNode;
@@ -5336,7 +5526,9 @@ export declare const IncomingMessageLayout: {
             onSendChallengeAction?: <T = object>(params: ChallengeActionParams) => Promise<T>;
             onStreamAnimationStart?: () => void;
             onStreamAnimationProgress?: () => void;
-            onStreamAnimationComplete?: () => void;
+            onStreamAnimationComplete?: (params: {
+                completed: boolean;
+            }) => void;
             onStreamAnimationHoldChange?: (holding: boolean) => void;
             messageTemplateErrorFallback?: ReactNode;
             messageTemplateLoadingFallback?: ReactNode;
@@ -5461,7 +5653,7 @@ declare interface LanguageSet extends Omit<AIAgentLanguageSet, 'strings'> {
     stringSet: StringSet;
 }
 
-export declare function LauncherBase({ className, children, isOpened, onClick, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, type, imageUrl, dir, animated, backgroundColor, size, hasUnread, }: LauncherProps): JSX.Element;
+export declare function LauncherBase({ className, children, isOpened, onClick, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, type, imageUrl, dir, animated, backgroundColor, size, hasUnread, }: LauncherProps_2): JSX.Element;
 
 declare type LauncherImageType = 'default_icon' | 'custom_image';
 
@@ -5471,6 +5663,15 @@ declare interface LauncherInfo {
 }
 
 declare type LauncherProps = {
+    opened: boolean;
+    setOpened: (opened: boolean) => void;
+    size?: number;
+    className?: string;
+    entryPoint?: LauncherRoute;
+    activeRoute?: LauncherRoute;
+};
+
+declare type LauncherProps_2 = {
     className?: string;
     children?: ReactNode;
     isOpened: boolean;
@@ -5486,6 +5687,8 @@ declare type LauncherProps = {
     hasUnread?: boolean;
 };
 
+export declare type LauncherRoute = 'Conversation' | 'ConversationList';
+
 declare interface LayoutContextValue<Props, Components extends Record<string, ComponentType<any>>> {
     Template: ComponentType<Props>;
     updateTemplate: (template: ComponentType<Props>) => void;
@@ -5664,6 +5867,477 @@ declare interface MemoryInfo {
  * */
 declare type MessageGroupType = 'single' | 'top' | 'bottom' | 'middle';
 
+/**
+ * One turn: the acknowledged user message and every bubble that answers it.
+ *
+ * `first` is the first bubble's span, opened at the send so it can time out and carry the
+ * typing; it joins `spans` once a bubble announces its stream. The block stops accepting
+ * bubbles once the one flagged last has closed its stream, and is discarded whole by the next
+ * send.
+ */
+declare type MessageLifecycleBlock = {
+    channelUrl: string;
+    userMessageId: number;
+    conversationId?: number;
+    first: MessageLifecycleEventStatsSpan;
+    firstAnnounced: boolean;
+    spans: Map<number, MessageLifecycleEventStatsSpan>;
+    // The bubble flagged `is_last_in_turn` on any of its frames; the block closes once its
+    // stream does, whether or not the closing frame repeats the flag.
+    lastMessageId?: number;
+    closed: boolean;
+};
+
+declare class MessageLifecycleEventStats extends AIAgentBaseStats {
+    private timestamps?: MessageLifecycleTimestamps;
+
+    /**
+     * The order these moments happen in is fixed, but the order they arrive in is not, so every
+     * one is stored as it came and the durations between them are left to be derived later.
+     */
+    setTimestamps(timestamps: MessageLifecycleTimestamps): this {
+        this.timestamps = timestamps;
+        return this;
+    }
+
+    /** A domain string, never a caught error, so no payload value can leak into the description. */
+    setFailure(failure: MessageLifecycleFailure): this {
+        this.setError(failure);
+        return this;
+    }
+
+    protected getStatType(): string {
+        return AI_AGENT_ASSERTION_STAT_TYPE;
+    }
+
+    protected getMetricKey(): string {
+        return METRIC_KEY_MESSAGE_LIFECYCLE_EVENT;
+    }
+
+    protected buildPayload(): AIAgentStatPayload | null {
+        const timestamps = this.timestamps;
+        if (!timestamps) return null;
+
+        // The reveal is measured from the send for the first bubble and from its own announcement
+        // for the bubbles after it.
+        const revealFrom = timestamps.messageSentAt ?? timestamps.streamStartAt;
+        const animationEndAt = timestamps.animationEndAt;
+        const value =
+        animationEndAt === undefined || revealFrom === undefined ? UNMEASURABLE_DURATION : animationEndAt - revealFrom;
+
+        return this.createPayload(value, {
+            extra: {
+                message_id: timestamps.messageId === undefined ? undefined : String(timestamps.messageId),
+                message_sent_at: timestamps.messageSentAt,
+                typing_start_at: timestamps.typingStartAt,
+                typing_end_at: timestamps.typingEndAt,
+                stream_start_at: timestamps.streamStartAt,
+                stream_failed_at: timestamps.streamFailedAt,
+                last_stream_at: timestamps.lastStreamAt,
+                stream_end_at: timestamps.streamEndAt,
+                animation_start_at: timestamps.animationStartAt,
+                animation_end_at: timestamps.animationEndAt,
+            },
+        });
+    }
+}
+
+/**
+ * One bubble being measured, from its announcement to the reveal that shows it. The first
+ * bubble's span opens earlier, at the acknowledged user message, so it also owns the wait for
+ * the reply to start.
+ *
+ * The span owns its own timers, so a discarded attempt cannot report on a later one: cancelling
+ * severs the metric reference, and a timer that fires afterwards finds nothing to record.
+ */
+declare class MessageLifecycleEventStatsSpan extends StatsSpanBase<MessageLifecycleEventStats, MessageLifecycleMeasure> {
+    protected measure: MessageLifecycleMeasure;
+
+    constructor(
+    stats: MessageLifecycleEventStats | null,
+    params: { messageSentAt?: number; stopBackgroundWatch: (() => boolean) | null },
+    ) {
+        // Nothing calls setVisible on this tracker, so a span is never hidden.
+        super(stats, true);
+        this.measure = {
+            messageSentAt: params.messageSentAt,
+            startTimeoutTimer: null,
+            stallTimer: null,
+            stopBackgroundWatch: params.stopBackgroundWatch,
+        };
+    }
+
+    /** Starts the window the input stays blocked for; a reply that never streams runs it out. */
+    armStartTimeout(): void {
+        this.measure.startTimeoutTimer = setTimeout(() => this.failWith('sent_timeout'), STREAM_START_TIMEOUT_MS);
+    }
+
+    setConversationId(conversationId?: number): void {
+        this.stats?.setConversationId(conversationId);
+    }
+
+    onTypingChanged(isAgentTyping: boolean): void {
+        if (!this.stats) return;
+
+        // Only the first pair of edges describes the wait; later ones belong to a later reply.
+        if (isAgentTyping) {
+            if (this.measure.typingStartAt === undefined) this.measure.typingStartAt = Date.now();
+            return;
+        }
+        if (this.measure.typingStartAt !== undefined && this.measure.typingEndAt === undefined)
+        this.measure.typingEndAt = Date.now();
+    }
+
+    /** Latches onto the bubble announcing its stream; nothing else this span sees can be a chunk. */
+    onStreamStart(message: ChatSDKBaseMessage): void {
+        if (!this.stats) return;
+
+        this.measure.streamMessageId = message.messageId;
+        this.measure.streamStartAt = Date.now();
+        this.clearStartTimeout();
+        this.armStall();
+    }
+
+    onStreamFrame(message: ChatSDKBaseMessage, advancesStream: boolean): void {
+        if (!this.stats) return;
+
+        const now = Date.now();
+        // Only a MEDI carries a chunk. The stall timer is armed by either, because a redelivered
+        // announcement still says the server is there.
+        if (advancesStream) this.measure.lastStreamAt = now;
+
+        if (messageExtension.isStreaming(message)) return this.armStall();
+
+        this.measure.streamEndAt = now;
+        this.clearStall();
+        if (this.measure.animationStartAt === undefined) this.failWith('animation_not_started');
+    }
+
+    onAnimationStart(): void {
+        if (!this.stats) return;
+        if (this.measure.animationStartAt === undefined) this.measure.animationStartAt = Date.now();
+    }
+
+    onAnimationComplete(completed: boolean): void {
+        if (!this.stats) return;
+
+        // A reveal cut short says nothing about how long the answer took to appear.
+        if (!completed) return this.cancel();
+
+        this.settle({ animationEndAt: Date.now() });
+    }
+
+    override cancel(): void {
+        this.clearTimers();
+        this.measure.stopBackgroundWatch?.();
+        super.cancel();
+    }
+
+    private failWith(failure: MessageLifecycleFailure): void {
+        if (!this.stats) return;
+
+        this.stats.setFailure(failure);
+        if (failure !== 'stream_failed') return this.settle({});
+
+        // The last chunk time only describes a stall, and a stall that never produced a chunk
+        // drops the stream keys entirely: their absence is what marks it in the payload.
+        this.settle(
+        this.measure.lastStreamAt === undefined
+        ? { streamFailedAt: Date.now(), streamStartAt: undefined }
+        : { streamFailedAt: Date.now(), lastStreamAt: this.measure.lastStreamAt },
+        );
+    }
+
+    private settle(ending: {
+        animationEndAt?: number;
+        streamFailedAt?: number;
+        lastStreamAt?: number;
+        streamStartAt?: number;
+    }): void {
+        if (!this.stats) return;
+
+        this.clearTimers();
+
+        // A backgrounded app stops rendering, so the moments after it went away are not the
+        // product's timing any more.
+        if (this.measure.stopBackgroundWatch?.()) return super.cancel();
+
+        this.stats.setTimestamps({
+            messageId: this.measure.streamMessageId,
+            messageSentAt: this.measure.messageSentAt,
+            typingStartAt: this.measure.typingStartAt,
+            typingEndAt: this.measure.typingEndAt,
+            streamStartAt: this.measure.streamStartAt,
+            streamEndAt: this.measure.streamEndAt,
+            animationStartAt: this.measure.animationStartAt,
+            ...ending,
+        });
+        this.commitOrDefer();
+    }
+
+    private armStall(): void {
+        this.clearStall();
+        this.measure.stallTimer = setTimeout(() => this.failWith('stream_failed'), STREAM_STALL_TIMEOUT_MS);
+    }
+
+    private clearTimers(): void {
+        this.clearStartTimeout();
+        this.clearStall();
+    }
+
+    private clearStartTimeout(): void {
+        if (this.measure.startTimeoutTimer !== null) clearTimeout(this.measure.startTimeoutTimer);
+        this.measure.startTimeoutTimer = null;
+    }
+
+    private clearStall(): void {
+        if (this.measure.stallTimer !== null) clearTimeout(this.measure.stallTimer);
+        this.measure.stallTimer = null;
+    }
+}
+
+/**
+ * Spec: message_lifecycle_event
+ *
+ * Records when each moment of one reply happened, from the user sending a message to the
+ * reply finishing its reveal. The moments are emitted as wall-clock times rather than
+ * durations, because their order of arrival is not guaranteed even though their order of
+ * occurrence is: deriving durations here would bake a wrong value into the sample.
+ *
+ * Timeline:
+ * - The user's message is acknowledged, which opens the block.
+ * - The agent starts and stops typing.
+ * - Each bubble announces a stream, streams its chunks, and closes it. A stream is announced
+ *   by a MESG and advanced by MEDIs, which the delivering event says and the collection's own
+ *   add/update does not — so the same announcement arriving twice is not a chunk.
+ * - Each bubble's reveal animation starts and finishes.
+ *
+ * Payload, one sample per bubble:
+ * - value: animation end minus message sent for the first bubble, minus stream start for the
+ *   bubbles after it, or -1 when the reveal never happened.
+ * - extra.message_id: the bubble.
+ * - extra.*_at: each moment that happened; the rest are left out. Only the first bubble
+ *   carries the send and typing moments, since only it was waited for.
+ * - error_description: sent_timeout, stream_failed or animation_not_started.
+ *
+ * Method call order:
+ * - `onUserMessageSent` opens a block and discards whatever was open.
+ * - Every other method addresses the open block; there is no handle for callers to hold,
+ *   because they are spread across the provider and both platform packages.
+ *
+ * Policy:
+ * - One block at a time. The next message the user sends discards whatever is still open,
+ *   spans included, and a discarded span is non-recording, so its own timers can no longer
+ *   report anything.
+ * - A reply split into bubbles is measured bubble by bubble: each announcement opens its own
+ *   span, and every span settles on its own. The block closes when the bubble flagged
+ *   `is_last_in_turn` closes its stream — the flag is only reliable then — and nothing waits
+ *   for a last bubble that never comes: the block is simply discarded by the next send.
+ * - Only bubbles that reach the screen are measured. A bubble is dropped when the reveal is
+ *   cut short, when it arrives already settled and so never animates, when it is deleted,
+ *   when the conversation goes away, or when the app was backgrounded, because none of those
+ *   say anything about how fast the product answered.
+ * - Every collection source is observed, because a reconnect delivers the rest of a stream
+ *   through a sync rather than a live event. Correlation is what scopes an event to this turn.
+ * - A reply that never starts streaming within the input block window is reported as a
+ *   timeout, which covers both silence and typing that leads nowhere.
+ * - A stream that closes before its reveal ever starts is a rendering fault, so it is reported
+ *   right away instead of waiting for an animation that is not coming.
+ */
+declare class MessageLifecycleEventStatsTracker extends StatsTrackerBase {
+    private block: MessageLifecycleBlock | null = null;
+    private watchBackgrounded?: BackgroundedWatcher;
+
+    setBackgroundedWatcher(watchBackgrounded?: BackgroundedWatcher): void {
+        this.watchBackgrounded = watchBackgrounded;
+    }
+
+    /** Opens a block for the message the user just got acknowledged. */
+    onUserMessageSent(params: { channelUrl: string; messageId: number; conversationId?: number }): void {
+        this.discardBlock();
+
+        const first = this.createSpan(params.conversationId, { messageSentAt: Date.now() });
+        first.armStartTimeout();
+        this.block = {
+            channelUrl: params.channelUrl,
+            userMessageId: params.messageId,
+            conversationId: params.conversationId,
+            first,
+            firstAnnounced: false,
+            spans: new Map(),
+            closed: false,
+        };
+    }
+
+    /**
+     * The conversation is initialized after the channel is exposed, so a block can open before
+     * its id exists — including for a turn that only ever commits on a timeout, which no later
+     * event would reach. The setter keeps the first real id it is given.
+     */
+    onConversationIdResolved(params: { channelUrl: string; conversationId?: number }): void {
+        const block = this.blockFor(params.channelUrl);
+        if (!block) return;
+
+        block.conversationId ??= params.conversationId;
+        block.first.setConversationId(params.conversationId);
+        block.spans.forEach((span) => span.setConversationId(params.conversationId));
+    }
+
+    onTypingChanged(params: { channelUrl: string; isAgentTyping: boolean }): void {
+        // Typing describes the wait for the first bubble; the span that carries it keeps ignoring
+        // later edges on its own.
+        this.blockFor(params.channelUrl)?.first.onTypingChanged(params.isAgentTyping);
+    }
+
+    onCollectionEvent(params: { event: GroupChannelMessagesCollectionEvent; channelUrl: string; aiAgentUserId: string }) {
+        const block = this.blockFor(params.channelUrl);
+        const event = params.event;
+        if (!block) return;
+        if (event.channelUrl !== params.channelUrl) return;
+
+        // A deleted bubble can no longer reach the screen, and the stall timer would report it as a
+        // stream that died rather than one that was removed.
+        if (event.kind === 'messagesDeleted') {
+            event.messages.forEach((message) => block.spans.get(message.messageId)?.cancel());
+            return;
+        }
+
+        if (event.kind === 'initialized') return;
+
+        // The source is not filtered. A reconnect delivers the rest of a stream through the
+        // collection's changelog sync rather than a live event (browser-e2e/tests/streaming.e2e.test.ts
+        // TC-CPE-08), and rejecting that recovery leaves the turn to run out its timers and report a
+        // failure the screen contradicts. Correlation is what scopes an event to this turn, and
+        // only a MEDI counts as a chunk, so a recovery closes the bubble without inventing one.
+        const advancesStream = event.source === CollectionEventSource.EVENT_MESSAGE_UPDATED;
+
+        event.messages.forEach((message) => {
+            if (!isSentBy(message, params.aiAgentUserId)) return;
+            // The reply names the message it answers, which is what ties it to this block.
+            if (parseAIResponseMessageData(message.data).userMessageId !== block.userMessageId) return;
+
+            this.observeReply(block, message, advancesStream);
+        });
+    }
+
+    onAnimationStart(params: { messageId: number }): void {
+        this.block?.spans.get(params.messageId)?.onAnimationStart();
+    }
+
+    onAnimationComplete(params: { messageId: number; completed: boolean }): void {
+        this.block?.spans.get(params.messageId)?.onAnimationComplete(params.completed);
+    }
+
+    /** The conversation going away leaves the turn unfinished, so nothing is reported. */
+    clearChannel(channelUrl?: string): void {
+        if (!channelUrl || !this.blockFor(channelUrl)) return;
+        this.discardBlock();
+    }
+
+    clear(): void {
+        this.discardBlock();
+    }
+
+    private observeReply(block: MessageLifecycleBlock, message: ChatSDKBaseMessage, advancesStream: boolean): void {
+        const streaming = messageExtension.isStreaming(message);
+
+        // Judged on the frames alone, so a bubble whose span is already settled or discarded can
+        // still end the turn.
+        if (isLastInTurn(message)) block.lastMessageId = message.messageId;
+        const closesTurn = block.lastMessageId === message.messageId && !streaming;
+
+        const known = block.spans.get(message.messageId);
+        if (known) {
+            known.onStreamFrame(message, advancesStream);
+            if (closesTurn) block.closed = true;
+            return;
+        }
+
+        if (block.closed) return;
+
+        if (!streaming) {
+            // A bubble that arrives already settled never animates — `useStreamingText` only reveals
+            // a row whose stream was on at mount — so it has no reveal to measure. Arriving as the
+            // first bubble it also ends the wait.
+            if (!block.firstAnnounced) block.first.cancel();
+            block.firstAnnounced = true;
+            if (closesTurn) block.closed = true;
+            return;
+        }
+
+        // The first bubble takes over the span that waited for it; later bubbles get their own.
+        const span = block.firstAnnounced ? this.createSpan(block.conversationId, {}) : block.first;
+        block.firstAnnounced = true;
+        span.onStreamStart(message);
+        block.spans.set(message.messageId, span);
+    }
+
+    private createSpan(
+    conversationId: number | undefined,
+    params: { messageSentAt?: number },
+    ): MessageLifecycleEventStatsSpan {
+        const stats = new MessageLifecycleEventStats()
+        .setConversationId(conversationId)
+        .setCommitCallback(this.commitCallback);
+
+        return new MessageLifecycleEventStatsSpan(stats, {
+            messageSentAt: params.messageSentAt,
+            stopBackgroundWatch: this.watchBackgrounded?.() ?? null,
+        });
+    }
+
+    private discardBlock(): void {
+        const block = this.block;
+        if (!block) return;
+
+        block.first.cancel();
+        block.spans.forEach((span) => span.cancel());
+        this.block = null;
+    }
+
+    /** The open block, only when it belongs to the channel in hand. */
+    private blockFor(channelUrl: string): MessageLifecycleBlock | undefined {
+        const block = this.block;
+        if (!block || block.channelUrl !== channelUrl) return undefined;
+        return block;
+    }
+}
+
+/** Why the turn never reached the screen. */
+declare type MessageLifecycleFailure = 'sent_timeout' | 'stream_failed' | 'animation_not_started';
+
+declare type MessageLifecycleMeasure = {
+    // The first bubble's span starts at the user's send and carries the wait; later bubbles start
+    // at their own announcement and carry none of these.
+    messageSentAt?: number;
+    typingStartAt?: number;
+    typingEndAt?: number;
+    streamMessageId?: number;
+    streamStartAt?: number;
+    lastStreamAt?: number;
+    streamEndAt?: number;
+    animationStartAt?: number;
+    startTimeoutTimer: TimeoutId | null;
+    stallTimer: TimeoutId | null;
+    stopBackgroundWatch: (() => boolean) | null;
+};
+
+/** Every moment of the bubble, as wall-clock times rather than durations. */
+declare type MessageLifecycleTimestamps = {
+    /** The bubble; absent when the reply never announced one. */
+    messageId?: number;
+    /** Only the first bubble of a turn was waited for, so only it carries the send and typing. */
+    messageSentAt?: number;
+    typingStartAt?: number;
+    typingEndAt?: number;
+    streamStartAt?: number;
+    streamFailedAt?: number;
+    lastStreamAt?: number;
+    streamEndAt?: number;
+    animationStartAt?: number;
+    animationEndAt?: number;
+};
+
 export declare const MessageListUILayout: {
     (props: PropsWithChildren): ReactNode;
     defaults: {
@@ -6070,6 +6744,21 @@ export declare interface NudgeMessageResponse {
     callbackUserMessage?: string;
 }
 
+declare interface NudgeMessageState {
+    /** The nudge to display; null while the messenger is opened or no nudge is active. */
+    nudgeMessage: NudgeMessageResponse | null;
+    /**
+     * Counts nudges received and never falls back when one is cleared; each platform's renderer keys
+     * the bubble on it to replay the entrance animation.
+     */
+    nudgeMessageKey: number;
+    dismissNudgeMessage: () => void;
+    /** Starts a new conversation from the nudge: creates a channel, opens the messenger, and sends the callback user message. */
+    startNudgeConversation: () => Promise<void>;
+}
+
+declare type NudgeMessageViewProps = NudgeMessageState;
+
 declare type NumberField = {
     key: string;
     type: 'number';
@@ -6085,6 +6774,20 @@ declare type NumberField = {
     };
 };
 
+declare type ObservedCollectionEvent = {
+    event: GroupChannelMessagesCollectionEvent;
+    channelUrl: string;
+    aiAgentUserId: string;
+    conversationId?: number;
+};
+
+declare type ObservedConversation = {
+    channelUrl: string;
+    aiAgentUserId: string;
+    messages: ChatSDKBaseMessage[];
+    conversationId?: number;
+};
+
 declare type OnJoinedProactiveConversation = (params: {
     channel: ChatSDKGroupChannel;
 }) => void;
@@ -6875,6 +7578,211 @@ declare type StreamAnimation = {
     holdStop: (id: string | number) => void;
 };
 
+declare class StreamingMessageValidationStats extends AIAgentBaseStats {
+    private durationMs?: number;
+    private messageId?: number;
+    private chunkIntervalsMs: number[] = [];
+    private regenerated = false;
+
+    setMessageId(messageId: number): this {
+        this.messageId = messageId;
+        return this;
+    }
+
+    setStream(params: { durationMs: number; chunkIntervalsMs: number[]; regenerated: boolean }): this {
+        this.durationMs = params.durationMs;
+        this.chunkIntervalsMs = params.chunkIntervalsMs;
+        this.regenerated = params.regenerated;
+        return this;
+    }
+
+    protected getStatType(): string {
+        return AI_AGENT_ASSERTION_STAT_TYPE;
+    }
+
+    protected getMetricKey(): string {
+        return METRIC_KEY_STREAMING_MESSAGE_VALIDATION;
+    }
+
+    protected buildPayload(): AIAgentStatPayload | null {
+        if (this.durationMs === undefined || this.messageId === undefined) return null;
+
+        return this.createPayload(this.durationMs, {
+            extra: {
+                message_id: String(this.messageId),
+                chunk_intervals_ms: this.chunkIntervalsMs,
+                regenerated: this.regenerated,
+            },
+        });
+    }
+}
+
+/**
+ * Spec: streaming_message_validation
+ *
+ * Measures how a single AI answer streamed in, and whether it was regenerated
+ * mid-flight. Tracking is keyed by message_id because one stream is one message.
+ *
+ * Timeline:
+ * - Start on the received message that announces a stream.
+ * - Each later update that changes the text is one chunk; its interval is measured from
+ *   the previous text change. An update that repeats the current text is not a chunk, so
+ *   a redelivered snapshot folds into the next real interval instead of inventing one.
+ * - Regeneration is a text that does not extend the previous text. It records a -1
+ *   marker followed by the interval from the last good chunk to the regenerated one.
+ * - End on the update that clears the stream flag.
+ *
+ * Payload:
+ * - value: MESG(stream=true) to MEDI(stream=false) duration.
+ * - extra.message_id: the streamed message id.
+ * - extra.chunk_intervals_ms: per-chunk intervals, with -1 markers at regenerations.
+ * - extra.regenerated: whether the answer was regenerated at least once.
+ *
+ * Policy:
+ * - Only realtime collection sources are observed; history redelivery is ignored.
+ * - Only a received message opens a record; an update for an untracked message belongs to a
+ *   stream that was already dropped, and reopening it would measure a fragment of it.
+ * - Only the AI agent's own streamed messages are tracked.
+ * - Only streams that end explicitly are emitted; the sample is otherwise dropped.
+ * - A new stream in the channel drops any stream still in flight, which is how a
+ *   stream that never terminates is discarded. A deleted message is dropped as it goes.
+ * - A stream that spans a backgrounding is dropped, because a throttled tab makes the
+ *   intervals measure the browser rather than the server.
+ */
+declare class StreamingMessageValidationStatsTracker extends MultiStatsTrackerBase<
+StreamingMessageValidationStats,
+StreamValidationMeasure
+> {
+    private watchBackgrounded?: BackgroundedWatcher;
+
+    /** Platform capability used to drop samples that spanned a backgrounding. */
+    setBackgroundedWatcher(watchBackgrounded?: BackgroundedWatcher): void {
+        this.watchBackgrounded = watchBackgrounded;
+    }
+
+    onCollectionEvent(params: ObservedCollectionEvent): void {
+        const event = params.event;
+        if (event.channelUrl !== params.channelUrl) return;
+
+        // A deleted message can no longer deliver the update that ends its stream, so the sample
+        // is gone with it — regardless of which source reported the deletion.
+        if (event.kind === 'messagesDeleted') {
+            event.messages.forEach((message) => {
+                const record = this.records.get(message.messageId);
+                if (record) this.drop(message.messageId, record);
+            });
+            return;
+        }
+
+        if (event.kind === 'initialized') return;
+        if (!isRealtimeSource(event.source)) return;
+
+        // Whether the collection added or updated the row says how the list absorbed the
+        // message, not whether the stream is starting or advancing; only the delivering event
+        // knows that, because a stream is announced by a MESG and advanced by MEDIs.
+        const announcesStream = event.source === CollectionEventSource.EVENT_MESSAGE_RECEIVED;
+
+        event.messages.forEach((message) => {
+            const record = this.records.get(message.messageId);
+
+            if (!record) {
+                // Stream metadata is an AI convention rather than a guarantee, so the sender is
+                // checked too: a handed-off human agent's message must never open a stream record.
+                if (announcesStream && isSentBy(message, params.aiAgentUserId) && messageExtension.isStreaming(message)) {
+                    this.start(message, params.channelUrl, params.conversationId);
+                }
+                return;
+            }
+            if (record.measure.channelUrl !== params.channelUrl) return;
+
+            // The conversation is initialized after the channel is exposed, so a stream can open
+            // before its id exists; the setter keeps the first real one it is given.
+            record.stats.setConversationId(params.conversationId);
+            this.advance(record, message);
+            if (!messageExtension.isStreaming(message)) this.finish(message.messageId, record);
+        });
+    }
+
+    clearChannel(channelUrl?: string): void {
+        if (!channelUrl) return;
+        this.records.forEach((record, messageId) => {
+            if (record.measure.channelUrl === channelUrl) this.drop(messageId, record);
+        });
+    }
+
+    clear(): void {
+        this.records.forEach((record, messageId) => this.drop(messageId, record));
+    }
+
+    private start(message: ChatSDKBaseMessage, channelUrl: string, conversationId?: number): void {
+        // A stream that never ended can no longer end once the next one begins.
+        this.clearChannel(channelUrl);
+
+        const startedAt = performance.now();
+        this.records.set(message.messageId, {
+            stats: new StreamingMessageValidationStats()
+            .setMessageId(message.messageId)
+            .setConversationId(conversationId)
+            .setCommitCallback(this.commitCallback),
+            measure: {
+                channelUrl,
+                startedAt,
+                lastAt: startedAt,
+                lastText: message.message,
+                chunkIntervalsMs: [],
+                regenerated: false,
+                stopBackgroundWatch: this.watchBackgrounded?.() ?? null,
+            },
+        });
+    }
+
+    private advance(
+    record: StatsRecord<StreamingMessageValidationStats, StreamValidationMeasure>,
+    message: ChatSDKBaseMessage,
+    ): void {
+        const measure = record.measure;
+        const text = message.message;
+
+        if (text === measure.lastText) return;
+
+        if (!text.startsWith(measure.lastText)) {
+            measure.regenerated = true;
+            measure.chunkIntervalsMs.push(REGENERATED_MARKER);
+        }
+
+        const now = performance.now();
+        measure.chunkIntervalsMs.push(Math.round(now - measure.lastAt));
+        measure.lastText = text;
+        measure.lastAt = now;
+    }
+
+    private finish(
+    messageId: number,
+    record: StatsRecord<StreamingMessageValidationStats, StreamValidationMeasure>,
+    ): void {
+        const measure = record.measure;
+        this.records.delete(messageId);
+
+        if (measure.stopBackgroundWatch?.()) return;
+
+        record.stats
+        .setStream({
+            durationMs: Math.round(performance.now() - measure.startedAt),
+            chunkIntervalsMs: measure.chunkIntervalsMs,
+            regenerated: measure.regenerated,
+        })
+        .commit();
+    }
+
+    private drop(
+    messageId: string | number,
+    record: StatsRecord<StreamingMessageValidationStats, StreamValidationMeasure>,
+    ): void {
+        record.measure.stopBackgroundWatch?.();
+        this.records.delete(messageId);
+    }
+}
+
 declare type StreamMeasure = {
     channelUrl?: string;
     deliveryTimer: TimeoutId | null;
@@ -7203,6 +8111,16 @@ declare class StreamStalledStatsTracker extends MultiStatsTrackerBase<StreamStal
 
 declare type StreamStallKind = 'delivery' | 'render';
 
+declare type StreamValidationMeasure = {
+    channelUrl: string;
+    startedAt: number;
+    lastAt: number;
+    lastText: string;
+    chunkIntervalsMs: number[];
+    regenerated: boolean;
+    stopBackgroundWatch: (() => boolean) | null;
+};
+
 /**
  * StringSet type for React components
  * Uses SNAKE_CASE keys for backward compatibility