@sendbird/ai-agent-messenger-react 1.32.0 → 1.33.0

package/dist/index.d.ts

@@ -331,7 +331,7 @@ declare abstract class AIAgentBaseStats {
         const existing = this.timers.get(key);
         if (existing?.startTime !== null && existing?.startTime !== undefined) return this;
 
-        this.timers.set(key, { startTime: Date.now(), endTime: null });
+        this.timers.set(key, { startTime: defaultStatsClock.now(), endTime: null });
         return this;
     }
 
@@ -341,7 +341,7 @@ declare abstract class AIAgentBaseStats {
         const existing = this.timers.get(key);
         if (!existing || existing.startTime === null || existing.endTime !== null) return this;
 
-        this.timers.set(key, { ...existing, endTime: Date.now() });
+        this.timers.set(key, { ...existing, endTime: defaultStatsClock.now() });
         return this;
     }
 
@@ -719,10 +719,11 @@ declare interface AIAgentInterface {
     /** @internal Agent version for conversation initialization */
     agentVersion?: number;
 
-    /** @internal Stats trackers for performance monitoring */
-    readonly statsTrackers: {
-        initialRender: ConversationInitialRenderStatsTracker;
-    };
+    /** @internal Schedules metrics work that should only start while the app is foregrounded. */
+    readonly scheduleForegroundTask?: ForegroundTaskScheduler;
+
+    /** @internal Stats trackers owned by this SDK instance. */
+    readonly statsTrackers: AIAgentStatsTrackers;
 
     /** Authenticates with the AI Agent server and establishes a session */
     authenticate: (sessionInfo: ManualSessionInfo | AnonymousSessionInfo) => Promise<MessengerSettingsResponse>;
@@ -797,12 +798,6 @@ declare interface AIAgentMessengerSessionContextValue {
     deauthenticate: () => Promise<void>;
 
     createAttachmentRules: (params: { channel?: ChatSDKGroupChannel; uploadSizeLimit?: number }) => AttachmentRules;
-    /**
-     * @internal
-     */
-    statsTrackers: {
-        initialRender: ConversationInitialRenderStatsTracker;
-    };
 }
 
 declare interface AIAgentMessengerSessionRef {
@@ -1070,6 +1065,23 @@ declare interface AIAgentStatPayload {
     extra?: Record<string, unknown>;
 }
 
+declare type AIAgentStatsTrackerCollection = {
+    conversationInitialRender: ConversationInitialRenderStatsTracker;
+    conversationNotInteractiveTimeout: ConversationNotInteractiveTimeoutStatsTracker;
+    recoveryNotInteractiveTimeout: RecoveryNotInteractiveTimeoutStatsTracker;
+    conversationListInitialRender: ConversationListInitialRenderStatsTracker;
+    aievAuthExpiredUnhandled: AIEVAuthExpiredUnhandledStatsTracker;
+    messagePendingStuck: MessagePendingStuckStatsTracker;
+    userPerceivedResponseTime: UserPerceivedResponseTimeStatsTracker;
+    streamStalled: StreamStalledStatsTracker;
+    typingIndicatorAbsentTimeout: TypingIndicatorAbsentTimeoutStatsTracker;
+    renderedContentUnusable: RenderedContentUnusableStatsTracker;
+};
+
+declare type AIAgentStatsTrackers = AIAgentStatsTrackerCollection & {
+    clear: () => void;
+};
+
 /**
  * Common string set interface shared between react and react-native packages
  * These are the base strings that both packages use
@@ -1254,6 +1266,33 @@ declare interface AIAgentStringSet {
     };
 }
 
+declare class AIEVAuthExpiredUnhandledStatsTracker {
+    private readonly callback: StatsAppendCallback;
+
+    constructor(callback: StatsAppendCallback) {
+        this.callback = callback;
+    }
+
+    onPayloadParseFailed(params: { aiAgentId: string }): void {
+        append(this.callback, METRIC_KEY_AIEV_AUTH_EXPIRED_UNHANDLED, 'payload_parse_failed', {
+            extra: { agent_id: params.aiAgentId },
+        });
+    }
+
+    onCallbackNotFound(params: { aiAgentId: string }): void {
+        append(this.callback, METRIC_KEY_AIEV_AUTH_EXPIRED_UNHANDLED, 'callback_not_found', {
+            extra: { agent_id: params.aiAgentId },
+        });
+    }
+
+    clear(): void {}
+}
+
+declare type AIResponseMessageMetadata = {
+    isStreaming: boolean;
+    userMessageId?: number;
+};
+
 declare type AnnouncementQueueMode = 'latestOnly' | 'ordered';
 
 declare interface AnnounceOptions {
@@ -1532,7 +1571,7 @@ declare interface ContextObject {
     context: Record<string, string>;
 }
 
-export declare const Conversation: ({ children, onNavigateToConversationList, channelUrl, onClearChannelUrl, shouldMarkAsRead, announcementsEnabled, initialFocusTarget, style, closedChannelUrl, onClearClosedChannelUrl, }: ConversationProps) => JSX.Element;
+export declare const Conversation: ({ children, onNavigateToConversationList, channelUrl, onClearChannelUrl, shouldMarkAsRead, announcementsEnabled, conversationStatsEnabled, initialFocusTarget, style, closedChannelUrl, onClearClosedChannelUrl, }: ConversationProps) => JSX.Element;
 
 export declare const ConversationContext: Context<ConversationContextValue | null>;
 
@@ -1541,11 +1580,13 @@ declare interface ConversationContextProps {
     channelUrl?: string;
     onClearChannelUrl?: () => void;
     shouldMarkAsRead?: boolean;
+    conversationStatsEnabled?: boolean;
 }
 
 export declare const ConversationContextProvider: ({ children, ...props }: PropsWithChildren<ConversationContextProps>) => JSX.Element;
 
 declare interface ConversationContextValue extends AIAgentConversationContextValue {
+    conversationStatsEnabled: boolean;
     scrollSource: ConversationScrollContextValue;
     goToActiveConversation: () => Promise<void>;
     onNavigateToConversationList?: () => void;
@@ -1664,24 +1705,17 @@ declare class ConversationInitialRenderStats extends AIAgentBaseStats {
         const extra: Record<string, unknown> = {
             ...this.extraData,
             present_method: this.presentMethod,
-            ...(authDuration !== null && { auth_duration: authDuration }),
-            ...(getChannelDuration !== null && { get_channel_duration: getChannelDuration }),
-            ...(getMessagesDuration !== null && { get_messages_duration: getMessagesDuration }),
-            ...(totalDurationFromCache !== null && { total_duration_from_cache: totalDurationFromCache }),
+            ...(authDuration !== null && { [DurationKey.AUTH]: authDuration }),
+            ...(getChannelDuration !== null && { [DurationKey.GET_CHANNEL]: getChannelDuration }),
+            ...(getMessagesDuration !== null && { [DurationKey.GET_MESSAGES]: getMessagesDuration }),
+            ...(totalDurationFromCache !== null && { [DurationKey.TOTAL_DURATION_FROM_CACHE]: totalDurationFromCache }),
         };
 
-        const payload: AIAgentStatPayload = {
-            key: this.getMetricKey(),
-            // Use "0" when totalDuration is null (error case)
-            value: totalDuration !== null ? String(totalDuration) : '0',
-        };
-
-        if (this.conversationId !== null) payload.conversation_id = this.conversationId;
-        if (this.errorCode !== null) payload.error_code = this.errorCode;
-        if (this.errorDescription !== null) payload.error_description = this.errorDescription;
-        if (Object.keys(extra).length > 0) payload.extra = extra;
-
-        return payload;
+        return createStatsPayload(this.getMetricKey(), totalDuration ?? 0, {
+            conversationId: this.conversationId ?? undefined,
+            error: this.errorCode !== null ? { code: this.errorCode, message: this.errorDescription ?? '' } : undefined,
+            extra,
+        });
     }
 }
 
@@ -1690,100 +1724,193 @@ declare class ConversationInitialRenderStats extends AIAgentBaseStats {
  */
 declare class ConversationInitialRenderStatsTracker {
     private readonly commitCallback: StatsAppendCallback;
+    private apiResultReceived = false;
+    private channelUrl?: string;
+    private consumed = false;
+    private consumedByAuthError = false;
     private presentMethod: PresentMethod = 'direct_present';
+    private renderedAfterApiResult = false;
     private stats: ConversationInitialRenderStats | null = null;
 
     constructor(commitCallback: StatsAppendCallback) {
         this.commitCallback = commitCallback;
     }
 
-    private getOrCreateStats(): ConversationInitialRenderStats {
-        if (!this.stats || this.stats.isCommitted()) {
+    private getOrCreateStats(): ConversationInitialRenderStats | null {
+        if (this.consumed) return null;
+        if (this.stats?.isCommitted()) {
+            this.consumed = true;
+            return null;
+        }
+        if (!this.stats) {
             this.stats = new ConversationInitialRenderStats()
             .setCommitCallback(this.commitCallback)
             .setPresentMethod(this.presentMethod);
+            this.apiResultReceived = false;
+            this.renderedAfterApiResult = false;
         }
         return this.stats;
     }
 
+    private getActiveStats(): ConversationInitialRenderStats | null {
+        if (this.consumed || !this.stats || this.stats.isCommitted()) return null;
+        return this.stats;
+    }
+
+    private matchesChannelUrl(channelUrl?: string): boolean {
+        return channelUrl === undefined || this.channelUrl === undefined || channelUrl === this.channelUrl;
+    }
+
+    private pinChannelUrl(channelUrl?: string): boolean {
+        if (channelUrl === undefined) return true;
+        if (!this.matchesChannelUrl(channelUrl)) return false;
+
+        this.channelUrl = channelUrl;
+        this.stats?.setChannelUrl(channelUrl);
+        return true;
+    }
+
+    private consume(commitResult: boolean): boolean {
+        if (commitResult) {
+            this.consumed = true;
+        }
+        return commitResult;
+    }
+
+    private commitIfReady(channelUrl?: string): boolean {
+        if (this.consumed || !this.stats || this.stats.isCommitted()) return true;
+        if (!this.matchesChannelUrl(channelUrl)) return false;
+        if (!this.apiResultReceived || !this.renderedAfterApiResult) return false;
+        return this.consume(this.stats.stopTimer(DurationKey.TOTAL_DURATION).commit());
+    }
+
+    start(channelUrl?: string): void {
+        const stats = this.getOrCreateStats();
+        if (!stats || !this.pinChannelUrl(channelUrl)) return;
+
+        stats.startTimer(DurationKey.TOTAL_DURATION).startTimer(DurationKey.TOTAL_DURATION_FROM_CACHE);
+    }
+
     onAuthStart(): void {
-        this.getOrCreateStats()
-        .startTimer(DurationKey.TOTAL_DURATION)
-        .startTimer(DurationKey.TOTAL_DURATION_FROM_CACHE)
-        .startTimer(DurationKey.AUTH);
+        if (this.consumedByAuthError) {
+            this.clear();
+        }
+        this.getOrCreateStats()?.startTimer(DurationKey.AUTH);
     }
 
     onAuthComplete(): void {
-        this.stats?.stopTimer(DurationKey.AUTH);
+        this.getActiveStats()?.stopTimer(DurationKey.AUTH);
     }
 
     onAuthError(error: Error): void {
-        if (this.stats && !this.stats.isCommitted()) {
-            this.stats
+        const stats = this.getActiveStats();
+        if (stats) {
+            const committed = this.consume(
+            stats
             .stopTimer(DurationKey.AUTH)
             .setError(error instanceof SendbirdError ? error.code : undefined, error.message)
             .stopTimer(DurationKey.TOTAL_DURATION)
-            .commit();
+            .commit(),
+            );
+            if (committed) {
+                this.consumedByAuthError = true;
+            }
         }
     }
 
-    onGetChannelStart(): void {
-        this.stats?.startTimer(DurationKey.GET_CHANNEL);
+    onGetChannelStart(channelUrl?: string): void {
+        const stats = this.getActiveStats();
+        if (!stats || !this.pinChannelUrl(channelUrl)) return;
+
+        stats.startTimer(DurationKey.GET_CHANNEL);
     }
 
-    onGetChannelComplete(conversationId?: number): void {
-        if (this.stats) {
-            this.stats.stopTimer(DurationKey.GET_CHANNEL);
-            if (conversationId !== undefined) {
-                this.stats.setConversationId(conversationId);
-            }
-            this.stats.startTimer(DurationKey.GET_MESSAGES);
+    onGetChannelComplete(params?: number | GetChannelCompleteParams): void {
+        const channelUrl = typeof params === 'object' ? params.channelUrl : undefined;
+        const conversationId = typeof params === 'object' ? params.conversationId : params;
+        const stats = this.getActiveStats();
+        if (!stats || !this.pinChannelUrl(channelUrl)) return;
+
+        stats.stopTimer(DurationKey.GET_CHANNEL);
+        if (conversationId !== undefined) {
+            stats.setConversationId(conversationId);
         }
+        stats.startTimer(DurationKey.GET_MESSAGES);
     }
 
-    onGetChannelError(error: Error): void {
-        if (this.stats && !this.stats.isCommitted()) {
-            this.stats
+    onGetChannelError(params: Error | GetChannelErrorParams): void {
+        const channelUrl = params instanceof Error ? undefined : params.channelUrl;
+        const error = params instanceof Error ? params : params.error;
+        const stats = this.getActiveStats();
+        if (stats && this.pinChannelUrl(channelUrl)) {
+            this.consume(
+            stats
             .stopTimer(DurationKey.GET_CHANNEL)
             .setError(error instanceof SendbirdError ? error.code : undefined, error.message)
             .stopTimer(DurationKey.TOTAL_DURATION)
-            .commit();
+            .commit(),
+            );
         }
     }
 
     onCacheResult(error: Error | null): void {
-        if (this.stats && !this.stats.isCommitted()) {
+        const stats = this.getActiveStats();
+        if (stats) {
             if (error) {
-                this.stats.setError(error instanceof SendbirdError ? error.code : undefined, error.message);
+                stats.setError(error instanceof SendbirdError ? error.code : undefined, error.message);
             }
-            this.stats.stopTimer(DurationKey.TOTAL_DURATION_FROM_CACHE);
+            stats.stopTimer(DurationKey.TOTAL_DURATION_FROM_CACHE);
         }
     }
 
     onApiResult(error: Error | null): void {
-        if (this.stats && !this.stats.isCommitted()) {
+        const stats = this.getActiveStats();
+        if (stats) {
             if (error) {
-                this.stats.setError(error instanceof SendbirdError ? error.code : undefined, error.message);
+                this.consume(
+                stats
+                .setError(error instanceof SendbirdError ? error.code : undefined, error.message)
+                .stopTimer(DurationKey.TOTAL_DURATION)
+                .stopTimer(DurationKey.GET_MESSAGES)
+                .commit(),
+                );
+                return;
             }
-            this.stats.stopTimer(DurationKey.TOTAL_DURATION).stopTimer(DurationKey.GET_MESSAGES).commit();
+            this.apiResultReceived = true;
+            this.renderedAfterApiResult = false;
+            stats.stopTimer(DurationKey.GET_MESSAGES);
+            this.commitIfReady();
         }
     }
 
     setChannelUrl(url: string): void {
-        this.stats?.setChannelUrl(url);
+        this.pinChannelUrl(url);
+    }
+
+    commitPending(): boolean {
+        const stats = this.getActiveStats();
+        return stats ? this.consume(stats.stopTimer(DurationKey.TOTAL_DURATION).commit()) : true;
     }
 
-    cleanup(): void {
-        this.stats?.commit();
+    markRendered(channelUrl?: string): boolean {
+        if (!this.matchesChannelUrl(channelUrl)) return false;
+
+        this.renderedAfterApiResult = true;
+        return this.commitIfReady(channelUrl);
     }
 
     setPresentMethod(method: PresentMethod): void {
         this.presentMethod = method;
-        this.stats?.setPresentMethod(method);
+        this.getActiveStats()?.setPresentMethod(method);
     }
 
     clear(): void {
         this.stats = null;
+        this.apiResultReceived = false;
+        this.channelUrl = undefined;
+        this.consumed = false;
+        this.consumedByAuthError = false;
+        this.renderedAfterApiResult = false;
     }
 }
 
@@ -1826,7 +1953,7 @@ export declare const ConversationLayout: {
 declare interface ConversationLayoutTemplateProps {
 }
 
-export declare const ConversationList: ({ conversationListLimit, conversationListFilter, children, onOpenConversationView, announcementsEnabled, style, }: ConversationListProps) => JSX.Element;
+export declare const ConversationList: ({ conversationListLimit, conversationListFilter, children, onOpenConversationView, announcementsEnabled, conversationListStatsEnabled, style, }: ConversationListProps) => JSX.Element;
 
 /**
  * Public interface for ConversationListCollection.
@@ -1855,10 +1982,11 @@ export declare const ConversationListContext: Context<ConversationListContextVal
 declare interface ConversationListContextProps {
     conversationListLimit?: number;
     conversationListFilter?: Partial<AIAgentGroupChannelFilter>;
+    conversationListStatsEnabled?: boolean;
     onOpenConversationView?: (channelUrl: string, status: 'open' | 'closed', options?: ConversationListOpenOptions) => void;
 }
 
-export declare function ConversationListContextProvider({ conversationListLimit, conversationListFilter, onOpenConversationView, children, }: PropsWithChildren<ConversationListContextProps>): JSX.Element;
+export declare function ConversationListContextProvider({ conversationListLimit, conversationListFilter, conversationListStatsEnabled, onOpenConversationView, children, }: PropsWithChildren<ConversationListContextProps>): JSX.Element;
 
 declare interface ConversationListContextValue extends AIAgentConversationListContextValue {
     onOpenConversationView: (channelUrl: string, status: 'open' | 'closed', options?: ConversationListOpenOptions) => void;
@@ -1916,6 +2044,156 @@ declare interface ConversationListHeaderTemplateProps {
     titleAlign?: 'start' | 'center' | 'end';
 }
 
+declare class ConversationListInitialRenderStatsTracker {
+    private readonly callback: StatsAppendCallback;
+    private readonly clock: StatsClock;
+    private measurement = createEmptyProgress();
+    private renderedCommitted = false;
+    private startedAt: number | null = null;
+    private listStartedAt: number | null = null;
+    private authStartedAt: number | null = null;
+    private authDuration: number | null = null;
+    private listDuration: number | null = null;
+    private presentMethod: PresentMethod = 'direct_present';
+    private committed = false;
+
+    constructor(callback: StatsAppendCallback, options?: TrackerOptions) {
+        this.callback = callback;
+        this.clock = getClock(options);
+    }
+
+    onInitializeStart(): void {
+        if (this.measurement.rendered) return;
+        if (this.measurement.initialized) {
+            this.clearMeasurementState();
+        }
+        this.renderedCommitted = false;
+        this.startMeasurement();
+    }
+
+    onListRequestStart(): void {
+        if (this.measurement.listStarted && !this.measurement.listCompleted && !this.measurement.rendered) {
+            this.clearMeasurementState();
+        }
+
+        this.markListRequestStartOnce();
+    }
+
+    onListRequestComplete(): void {
+        this.markListRequestCompleteOnce();
+    }
+
+    onRendered(): void {
+        this.markRenderedOnce();
+    }
+
+    setPresentMethod(method: PresentMethod): void {
+        this.presentMethod = method;
+    }
+
+    start(presentMethod?: PresentMethod): void {
+        if (this.committed) return;
+        this.startedAt = this.clock.now();
+        if (presentMethod) this.presentMethod = presentMethod;
+    }
+
+    onAuthStart(): void {
+        if (this.committed) {
+            this.clearMeasurementState();
+            this.renderedCommitted = false;
+        }
+        this.authDuration = null;
+        this.authStartedAt = this.clock.now();
+    }
+
+    onAuthComplete(): void {
+        if (this.committed || this.authDuration !== null) return;
+        if (this.authStartedAt === null) {
+            this.authDuration = 0;
+            return;
+        }
+        this.authDuration = this.clock.now() - this.authStartedAt;
+        this.authStartedAt = null;
+    }
+
+    markListRequestStart(): void {
+        if (this.committed) return;
+        if (this.startedAt === null) this.start();
+        this.listStartedAt = this.clock.now();
+    }
+
+    markListRequestComplete(): void {
+        if (this.committed || this.listStartedAt === null) return;
+        this.listDuration = this.clock.now() - this.listStartedAt;
+    }
+
+    markRendered(): void {
+        if (this.committed || this.startedAt === null) return;
+        this.committed = true;
+        append(this.callback, METRIC_KEY_CONVERSATION_LIST_INITIAL_RENDER, this.clock.now() - this.startedAt, {
+            extra: {
+                ...(this.authDuration !== null && { auth_duration_ms: this.authDuration }),
+                ...(this.listDuration !== null && { get_list_duration_ms: this.listDuration }),
+                present_method: this.presentMethod,
+            },
+        });
+    }
+
+    clear(): void {
+        this.clearMeasurementState();
+        this.clearAuthState();
+        this.renderedCommitted = false;
+    }
+
+    private clearMeasurementState(): void {
+        this.startedAt = null;
+        this.listStartedAt = null;
+        this.listDuration = null;
+        this.committed = false;
+        this.measurement = createEmptyProgress();
+    }
+
+    private clearAuthState(): void {
+        this.authStartedAt = null;
+        this.authDuration = null;
+    }
+
+    private startMeasurement(): void {
+        if (this.measurement.initialized) return;
+
+        this.clearMeasurementState();
+        this.start();
+        this.measurement.initialized = true;
+    }
+
+    private markListRequestStartOnce(): void {
+        this.startMeasurement();
+        if (this.measurement.listStarted) return;
+
+        this.markListRequestStart();
+        this.measurement.listStarted = true;
+    }
+
+    private markListRequestCompleteOnce(): void {
+        this.markListRequestStartOnce();
+        if (this.measurement.listCompleted) return;
+
+        this.markListRequestComplete();
+        this.measurement.listCompleted = true;
+    }
+
+    private markRenderedOnce(): void {
+        if (this.renderedCommitted) return;
+
+        this.startMeasurement();
+        if (this.measurement.rendered) return;
+
+        this.markRendered();
+        this.measurement.rendered = true;
+        this.renderedCommitted = true;
+    }
+}
+
 export declare const ConversationListItemLayout: {
     (props: PropsWithChildren): ReactNode;
     defaults: {
@@ -1985,6 +2263,7 @@ export declare type ConversationListProps = PropsWithChildren<{
     conversationListFilter?: Partial<AIAgentGroupChannelFilter>;
     onOpenConversationView?: (channelUrl: string, status: 'open' | 'closed', options?: ConversationListOpenOptions) => void;
     announcementsEnabled?: boolean;
+    conversationListStatsEnabled?: boolean;
     /** Custom styles for the conversation list container. */
     style?: CSSProperties;
 }>;
@@ -2008,12 +2287,138 @@ declare type ConversationMessageEventPayload =
     messages: ChatSDKBaseMessage[];
 };
 
+declare type ConversationNotInteractiveMeasurement = {
+    timer: TimeoutId | null;
+    startedAt: number;
+    committed: boolean;
+    inputEnabled: boolean;
+    phaseReached: ConversationNotInteractivePhase;
+    historyLoadResult: HistoryLoadResult;
+    conversationId?: number;
+    channelUrl?: string;
+};
+
+declare type ConversationNotInteractivePhase = 'auth' | 'channel_join' | 'history_load' | 'input_enable' | 'render';
+
+declare class ConversationNotInteractiveTimeoutStatsTracker {
+    private readonly callback: StatsAppendCallback;
+    private readonly clock: StatsClock;
+    private readonly setTimeoutFn: typeof setTimeout;
+    private readonly clearTimeoutFn: typeof clearTimeout;
+    private readonly measurements = new Map<string, ConversationNotInteractiveMeasurement>();
+
+    constructor(callback: StatsAppendCallback, options?: TimedTrackerOptions) {
+        this.callback = callback;
+        this.clock = getClock(options);
+        this.setTimeoutFn = getSetTimeout(options);
+        this.clearTimeoutFn = getClearTimeout(options);
+    }
+
+    start(params?: { channelUrl?: string; conversationId?: number }): void {
+        const key = this.getKey(params?.channelUrl);
+        this.clearKey(key);
+
+        const measurement = {
+            startedAt: this.clock.now(),
+            channelUrl: params?.channelUrl,
+            conversationId: params?.conversationId,
+            committed: false,
+            inputEnabled: false,
+            phaseReached: 'auth' as ConversationNotInteractivePhase,
+            historyLoadResult: 'pending' as HistoryLoadResult,
+            timer: null as TimeoutId | null,
+        };
+        measurement.timer = this.setTimeoutFn(() => this.commitTimeout(key), 10_000);
+        this.measurements.set(key, measurement);
+    }
+
+    markChannelJoined(conversationId?: number, channelUrl?: string): void {
+        const measurement = this.getMeasurement(channelUrl);
+        if (!measurement || measurement.committed) return;
+        measurement.phaseReached = 'channel_join';
+        if (conversationId !== undefined) measurement.conversationId = conversationId;
+    }
+
+    markHistoryLoaded(result: HistoryLoadResult, channelUrl?: string): void {
+        const measurement = this.getMeasurement(channelUrl);
+        if (!measurement || measurement.committed) return;
+        measurement.phaseReached = 'history_load';
+        measurement.historyLoadResult = result;
+        this.cancelIfReady(channelUrl);
+    }
+
+    markInputEnabled(channelUrl?: string): void {
+        const measurement = this.getMeasurement(channelUrl);
+        if (!measurement || measurement.committed) return;
+        measurement.phaseReached = 'input_enable';
+        measurement.inputEnabled = true;
+        this.cancelIfReady(channelUrl);
+    }
+
+    markRendered(channelUrl?: string): void {
+        const measurement = this.getMeasurement(channelUrl);
+        if (!measurement || measurement.committed) return;
+        measurement.phaseReached = 'render';
+    }
+
+    clear(): void {
+        this.measurements.forEach((measurement) => clearTimer(measurement.timer, this.clearTimeoutFn));
+        this.measurements.clear();
+    }
+
+    clearChannel(channelUrl?: string): void {
+        if (channelUrl === undefined) return;
+        this.clearKey(this.getKey(channelUrl));
+    }
+
+    private clearKey(key: string): void {
+        const measurement = this.measurements.get(key);
+        if (!measurement) return;
+        clearTimer(measurement.timer, this.clearTimeoutFn);
+        this.measurements.delete(key);
+    }
+
+    private cancelIfReady(channelUrl?: string): void {
+        const measurement = this.getMeasurement(channelUrl);
+        if (!measurement || !measurement.inputEnabled || measurement.historyLoadResult === 'pending') return;
+        this.clearKey(this.getKey(measurement.channelUrl));
+    }
+
+    private commitTimeout(key: string): void {
+        const measurement = this.measurements.get(key);
+        if (!measurement || measurement.committed) return;
+        measurement.committed = true;
+        measurement.timer = null;
+        append(this.callback, METRIC_KEY_CONVERSATION_NOT_INTERACTIVE_TIMEOUT, this.clock.now() - measurement.startedAt, {
+            conversationId: measurement.conversationId,
+            error: { message: METRIC_KEY_CONVERSATION_NOT_INTERACTIVE_TIMEOUT },
+            extra: {
+                outcome: 'timeout',
+                phase_reached: measurement.phaseReached,
+                history_load_result: measurement.historyLoadResult,
+            },
+        });
+        this.measurements.delete(key);
+    }
+
+    private getMeasurement(channelUrl?: string): ConversationNotInteractiveMeasurement | undefined {
+        if (channelUrl !== undefined) return this.measurements.get(this.getKey(channelUrl));
+        if (this.measurements.size === 1) return Array.from(this.measurements.values())[0];
+        return this.measurements.get(this.getKey());
+    }
+
+    private getKey(channelUrl?: string): string {
+        return channelUrl ?? '__default__';
+    }
+}
+
 export declare type ConversationProps = PropsWithChildren<{
     channelUrl?: string;
     onClearChannelUrl?: () => void;
     onNavigateToConversationList?: () => void;
     shouldMarkAsRead?: boolean;
     announcementsEnabled?: boolean;
+    conversationStatsEnabled?: boolean;
     initialFocusTarget?: ConversationInitialFocusTarget;
     /** Custom styles for the conversation container. */
     style?: CSSProperties;
@@ -2209,12 +2614,22 @@ declare interface Dispatcher {
     ): void;
 }
 
+declare enum DurationKey {
+    AUTH = 'auth_duration_ms',
+    GET_CHANNEL = 'get_channel_duration_ms',
+    GET_MESSAGES = 'get_messages_duration_ms',
+    TOTAL_DURATION = 'total_duration_ms',
+    TOTAL_DURATION_FROM_CACHE = 'total_duration_from_cache_ms',
+}
+
 declare type ErrorAnnouncementParams =
 | { type: 'fileSizeExceeded'; maxSizeMB?: number }
 | { type: 'sendFailed' }
 | { type: 'csatFormError' }
 | { type: 'generic'; message: string };
 
+declare type ErrorLike = StatsPayloadError;
+
 /**
  * For better understanding: https://sendbird.atlassian.net/wiki/spaces/AA/pages/3075014695/Extended+Message+Payload+Spec
  */
@@ -2348,6 +2763,8 @@ declare interface FixedMessengerStyleProps {
     launcherSize?: number;
 }
 
+declare type ForegroundTaskScheduler = (start: () => void) => void | (() => void);
+
 declare interface Form {
     key: string;
     version: number;
@@ -2377,6 +2794,16 @@ export declare interface FunctionCallsInfo {
     };
 }
 
+declare type GetChannelCompleteParams = {
+    channelUrl?: string;
+    conversationId?: number;
+};
+
+declare type GetChannelErrorParams = {
+    channelUrl?: string;
+    error: Error;
+};
+
 export declare interface GroundednessInfo {
     id: number;
     source_type:
@@ -2399,6 +2826,8 @@ export declare interface GroundednessInfo {
  */
 declare type HexColor = `#${string}`;
 
+declare type HistoryLoadResult = 'success' | 'verified_empty' | 'failed' | 'pending';
+
 export declare type IconComponent = AIAgentIconComponent;
 
 export declare type IconComponentProps = AIAgentIconComponentProps;
@@ -2480,13 +2909,8 @@ export declare const IncomingMessageLayout: {
                 };
             }) => ReactNode;
             SuggestedReplies: ({ extendedMessagePayload, onClickSuggestedReply, suggestedRepliesDirection, }: IncomingMessageProps) => ReactNode;
-            MessageTemplate: (props: {
-                onGetCachedMessageTemplate?: ((templateKey: string) => string | null) | undefined;
-                onRequestMessageTemplate?: ((templateKey: string) => Promise<string>) | undefined;
-                onHandleTemplateInternalAction?: ((action: Action) => void) | undefined;
-                messageTemplateErrorFallback?: ReactNode;
-                messageTemplateLoadingFallback?: ReactNode;
-                extendedMessagePayload?: Partial<ExtendedMessagePayload> | undefined;
+            MessageTemplate: (props: Pick<IncomingMessageProps, "onGetCachedMessageTemplate" | "onRequestMessageTemplate" | "onHandleTemplateInternalAction" | "messageTemplateErrorFallback" | "messageTemplateLoadingFallback" | "extendedMessagePayload"> & {
+                statsCallbacks?: Pick<IncomingMessageStatsCallbacks, "onMessageTemplateError">;
             }) => ReactNode;
             CustomMessageTemplate: (_: ({
                 messageType: "user";
@@ -2950,7 +3374,9 @@ export declare const IncomingMessageLayout: {
             })) => ReactNode;
             CTAButton: ({ extendedMessagePayload, onClickCTA, }: IncomingMessageProps) => ReactNode;
             Citation: ({ extendedMessagePayload, onClickCitation, }: IncomingMessageProps) => ReactNode;
-            Form: (props: IncomingMessageProps) => ReactNode;
+            Form: (props: IncomingMessageProps & {
+                statsCallbacks?: Pick<IncomingMessageStatsCallbacks, "onFormRenderError">;
+            }) => ReactNode;
             Feedback: ({ isBotMessage, isConversationClosed, isStreaming, isFeedbackEnabled, isFeedbackCommentEnabled, extendedMessagePayload, onFeedbackUpdate, }: IncomingMessageProps) => ReactNode;
             MessageLogs: (_: IncomingMessageProps) => ReactNode;
         };
@@ -2975,13 +3401,8 @@ export declare const IncomingMessageLayout: {
     };
     }) => ReactNode;
     SuggestedReplies: ({ extendedMessagePayload, onClickSuggestedReply, suggestedRepliesDirection, }: IncomingMessageProps) => ReactNode;
-    MessageTemplate: (props: {
-    onGetCachedMessageTemplate?: ((templateKey: string) => string | null) | undefined;
-    onRequestMessageTemplate?: ((templateKey: string) => Promise<string>) | undefined;
-    onHandleTemplateInternalAction?: ((action: Action) => void) | undefined;
-    messageTemplateErrorFallback?: ReactNode;
-    messageTemplateLoadingFallback?: ReactNode;
-    extendedMessagePayload?: Partial<ExtendedMessagePayload> | undefined;
+    MessageTemplate: (props: Pick<IncomingMessageProps, "onGetCachedMessageTemplate" | "onRequestMessageTemplate" | "onHandleTemplateInternalAction" | "messageTemplateErrorFallback" | "messageTemplateLoadingFallback" | "extendedMessagePayload"> & {
+    statsCallbacks?: Pick<IncomingMessageStatsCallbacks, "onMessageTemplateError">;
     }) => ReactNode;
     CustomMessageTemplate: (_: ({
     messageType: "user";
@@ -3445,7 +3866,9 @@ export declare const IncomingMessageLayout: {
     })) => ReactNode;
     CTAButton: ({ extendedMessagePayload, onClickCTA, }: IncomingMessageProps) => ReactNode;
     Citation: ({ extendedMessagePayload, onClickCitation, }: IncomingMessageProps) => ReactNode;
-    Form: (props: IncomingMessageProps) => ReactNode;
+    Form: (props: IncomingMessageProps & {
+    statsCallbacks?: Pick<IncomingMessageStatsCallbacks, "onFormRenderError">;
+    }) => ReactNode;
     Feedback: ({ isBotMessage, isConversationClosed, isStreaming, isFeedbackEnabled, isFeedbackCommentEnabled, extendedMessagePayload, onFeedbackUpdate, }: IncomingMessageProps) => ReactNode;
     MessageLogs: (_: IncomingMessageProps) => ReactNode;
     }>>;
@@ -3465,13 +3888,8 @@ export declare const IncomingMessageLayout: {
     };
     }) => ReactNode;
     SuggestedReplies: ({ extendedMessagePayload, onClickSuggestedReply, suggestedRepliesDirection, }: IncomingMessageProps) => ReactNode;
-    MessageTemplate: (props: {
-    onGetCachedMessageTemplate?: ((templateKey: string) => string | null) | undefined;
-    onRequestMessageTemplate?: ((templateKey: string) => Promise<string>) | undefined;
-    onHandleTemplateInternalAction?: ((action: Action) => void) | undefined;
-    messageTemplateErrorFallback?: ReactNode;
-    messageTemplateLoadingFallback?: ReactNode;
-    extendedMessagePayload?: Partial<ExtendedMessagePayload> | undefined;
+    MessageTemplate: (props: Pick<IncomingMessageProps, "onGetCachedMessageTemplate" | "onRequestMessageTemplate" | "onHandleTemplateInternalAction" | "messageTemplateErrorFallback" | "messageTemplateLoadingFallback" | "extendedMessagePayload"> & {
+    statsCallbacks?: Pick<IncomingMessageStatsCallbacks, "onMessageTemplateError">;
     }) => ReactNode;
     CustomMessageTemplate: (_: ({
     messageType: "user";
@@ -3935,19 +4353,16 @@ export declare const IncomingMessageLayout: {
     })) => ReactNode;
     CTAButton: ({ extendedMessagePayload, onClickCTA, }: IncomingMessageProps) => ReactNode;
     Citation: ({ extendedMessagePayload, onClickCitation, }: IncomingMessageProps) => ReactNode;
-    Form: (props: IncomingMessageProps) => ReactNode;
+    Form: (props: IncomingMessageProps & {
+    statsCallbacks?: Pick<IncomingMessageStatsCallbacks, "onFormRenderError">;
+    }) => ReactNode;
     Feedback: ({ isBotMessage, isConversationClosed, isStreaming, isFeedbackEnabled, isFeedbackCommentEnabled, extendedMessagePayload, onFeedbackUpdate, }: IncomingMessageProps) => ReactNode;
     MessageLogs: (_: IncomingMessageProps) => ReactNode;
     }>;
 } & {
     MessageTemplate: (props: {
-        component: (props: {
-            onGetCachedMessageTemplate?: ((templateKey: string) => string | null) | undefined;
-            onRequestMessageTemplate?: ((templateKey: string) => Promise<string>) | undefined;
-            onHandleTemplateInternalAction?: ((action: Action) => void) | undefined;
-            messageTemplateErrorFallback?: ReactNode;
-            messageTemplateLoadingFallback?: ReactNode;
-            extendedMessagePayload?: Partial<ExtendedMessagePayload> | undefined;
+        component: (props: Pick<IncomingMessageProps, "onGetCachedMessageTemplate" | "onRequestMessageTemplate" | "onHandleTemplateInternalAction" | "messageTemplateErrorFallback" | "messageTemplateLoadingFallback" | "extendedMessagePayload"> & {
+            statsCallbacks?: Pick<IncomingMessageStatsCallbacks, "onMessageTemplateError">;
         }) => ReactNode;
     }) => null;
     SenderName: (props: {
@@ -4456,7 +4871,9 @@ export declare const IncomingMessageLayout: {
         component: ({ extendedMessagePayload, onClickCitation, }: IncomingMessageProps) => ReactNode;
     }) => null;
     Form: (props: {
-        component: (props: IncomingMessageProps) => ReactNode;
+        component: (props: IncomingMessageProps & {
+            statsCallbacks?: Pick<IncomingMessageStatsCallbacks, "onFormRenderError">;
+        }) => ReactNode;
     }) => null;
     Feedback: (props: {
         component: ({ isBotMessage, isConversationClosed, isStreaming, isFeedbackEnabled, isFeedbackCommentEnabled, extendedMessagePayload, onFeedbackUpdate, }: IncomingMessageProps) => ReactNode;
@@ -4469,6 +4886,13 @@ export declare const IncomingMessageLayout: {
 export declare type IncomingMessageProps<T extends IncomingMessageUnion['messageType'] = IncomingMessageUnion['messageType']> =
 PickMessageProps<IncomingMessageUnion, T>;
 
+declare type IncomingMessageStatsCallbacks = {
+    onVisibleTextProgress?: (displayedLength: number) => void;
+    onRenderedTextProgress?: (displayedLength: number) => void;
+    onMessageTemplateError?: (error: Error) => void;
+    onFormRenderError?: (error: Error) => void;
+};
+
 declare type IncomingMessageTemplateProps = IncomingMessageProps & Partial<InternalExtraProps>;
 
 declare type IncomingMessageUnion =
@@ -4508,7 +4932,7 @@ declare type InputState =
 
 declare type InternalExtraProps = {
     maxBodyWidth?: number;
-    testerMode?: boolean;
+    statsCallbacks?: IncomingMessageStatsCallbacks;
 };
 
 declare type InternalExtraProps_2 = {
@@ -4651,6 +5075,95 @@ export declare const MessageListUILayout: {
 
 export declare const MessageLogs: ({ actionbook, functionCalls, groundedness, agentMessageTemplates, flaggedTypes, onClickActionbook, onClickFunctionCall, onClickFunctionCallDetail, onClickGroundedness, onClickAgentMessageTemplate, topContent, bottomContent, renderCustomGroundednessIcon, style, }: Props_2) => JSX.Element;
 
+declare class MessagePendingStuckStatsTracker {
+    private readonly callback: StatsAppendCallback;
+    private readonly setTimeoutFn: typeof setTimeout;
+    private readonly clearTimeoutFn: typeof clearTimeout;
+    private readonly measurements = new Map<string, PendingMeasurement>();
+
+    constructor(callback: StatsAppendCallback, options?: PendingStuckTrackerOptions) {
+        this.callback = callback;
+        this.setTimeoutFn = getSetTimeout(options);
+        this.clearTimeoutFn = getClearTimeout(options);
+    }
+
+    start(params: {
+        requestId: string;
+        channelUrl?: string;
+        messageType: PendingMessageType;
+        tracksUploadProgress?: boolean;
+    }): void {
+        if (!params.requestId || this.measurements.has(params.requestId)) return;
+
+        const usesUploadProgress = params.messageType !== 'text' && params.tracksUploadProgress === true;
+        const measurement: PendingMeasurement = {
+            channelUrl: params.channelUrl,
+            messageType: params.messageType,
+            stuckReason: usesUploadProgress ? 'upload_no_progress' : 'pending_too_long',
+            timer: null,
+        };
+        const timeoutMs = usesUploadProgress ? FILE_UPLOAD_NO_PROGRESS_TIMEOUT_MS : TEXT_PENDING_TIMEOUT_MS;
+        measurement.timer = this.setTimeoutFn(() => this.detect(params.requestId), timeoutMs);
+        this.measurements.set(params.requestId, measurement);
+    }
+
+    resolve(params: { requestId: string }): void {
+        const measurement = this.measurements.get(params.requestId);
+        if (!measurement) return;
+
+        clearTimer(measurement.timer, this.clearTimeoutFn);
+        this.measurements.delete(params.requestId);
+    }
+
+    disappear(params: { requestId: string }): void {
+        const measurement = this.measurements.get(params.requestId);
+        if (!measurement) return;
+
+        clearTimer(measurement.timer, this.clearTimeoutFn);
+        this.measurements.delete(params.requestId);
+    }
+
+    markUploadProgress(requestId: string): void {
+        const measurement = this.measurements.get(requestId);
+        if (!measurement) return;
+        if (measurement.stuckReason !== 'upload_no_progress') return;
+
+        clearTimer(measurement.timer, this.clearTimeoutFn);
+        measurement.timer = this.setTimeoutFn(() => this.detect(requestId), FILE_UPLOAD_NO_PROGRESS_TIMEOUT_MS);
+    }
+
+    clear(): void {
+        this.measurements.forEach((measurement) => clearTimer(measurement.timer, this.clearTimeoutFn));
+        this.measurements.clear();
+    }
+
+    clearChannel(channelUrl?: string): void {
+        if (!channelUrl) return;
+        this.measurements.forEach((measurement, requestId) => {
+            if (measurement.channelUrl !== channelUrl) return;
+            clearTimer(measurement.timer, this.clearTimeoutFn);
+            this.measurements.delete(requestId);
+        });
+    }
+
+    private detect(requestId: string): void {
+        const measurement = this.measurements.get(requestId);
+        if (!measurement) return;
+
+        this.measurements.delete(requestId);
+        this.commit(requestId, measurement);
+    }
+
+    private commit(requestId: string, measurement: PendingMeasurement): void {
+        append(this.callback, METRIC_KEY_MESSAGE_PENDING_STUCK, measurement.stuckReason, {
+            extra: {
+                message_type: measurement.messageType,
+                request_id: requestId,
+            },
+        });
+    }
+}
+
 declare interface MessageTemplateCache {
     set(key: string, value: string): void;
     get(key: string): string | null;
@@ -4915,6 +5428,7 @@ export declare const OutgoingMessageLayout: {
             MediaMessageBody: typeof OutgoingImageBody;
             FileMessageBody: typeof OutgoingFileBody;
             MultipleFilesMessageBody: ({ sendingStatus, files, metadata, onClickMedia, onClickMediaFiles, children, }: OutgoingMessageBodyProps<"multipleFiles">) => JSX.Element;
+            MessageLogs: (_: OutgoingMessageProps) => ReactNode;
         };
     };
     Template: ({ template, children }: {
@@ -4929,6 +5443,7 @@ export declare const OutgoingMessageLayout: {
     MediaMessageBody: typeof OutgoingImageBody;
     FileMessageBody: typeof OutgoingFileBody;
     MultipleFilesMessageBody: ({ sendingStatus, files, metadata, onClickMedia, onClickMediaFiles, children, }: OutgoingMessageBodyProps<"multipleFiles">) => JSX.Element;
+    MessageLogs: (_: OutgoingMessageProps) => ReactNode;
     }>>;
     useContext: () => LayoutContextValue<OutgoingMessageProps, {
     SendingStatus: ({ sendingStatus }: OutgoingMessageProps) => ReactNode;
@@ -4938,6 +5453,7 @@ export declare const OutgoingMessageLayout: {
     MediaMessageBody: typeof OutgoingImageBody;
     FileMessageBody: typeof OutgoingFileBody;
     MultipleFilesMessageBody: ({ sendingStatus, files, metadata, onClickMedia, onClickMediaFiles, children, }: OutgoingMessageBodyProps<"multipleFiles">) => JSX.Element;
+    MessageLogs: (_: OutgoingMessageProps) => ReactNode;
     }>;
 } & {
     SentTime: (props: {
@@ -4958,6 +5474,9 @@ export declare const OutgoingMessageLayout: {
     MultipleFilesMessageBody: (props: {
         component: ({ sendingStatus, files, metadata, onClickMedia, onClickMediaFiles, children, }: OutgoingMessageBodyProps<"multipleFiles">) => JSX.Element;
     }) => null;
+    MessageLogs: (props: {
+        component: (_: OutgoingMessageProps) => ReactNode;
+    }) => null;
     SendingStatus: (props: {
         component: ({ sendingStatus }: OutgoingMessageProps) => ReactNode;
     }) => null;
@@ -5035,6 +5554,31 @@ declare interface PaletteTextEmphasis {
     textDisabled: string;
 }
 
+declare type PendingAIResponseRaw = {
+    messageId: number;
+    channelUrl?: string;
+    aiResponse: AIResponseMessageMetadata;
+    firstChunkAt: number;
+};
+
+declare type PendingAIResponseStart = {
+    channelUrl?: string;
+    startedAt: number;
+};
+
+declare type PendingMeasurement = {
+    channelUrl?: string;
+    messageType: PendingMessageType;
+    stuckReason: PendingStuckReason;
+    timer: TimeoutId | null;
+};
+
+declare type PendingMessageType = 'text' | 'file_image' | 'file_video' | 'file_document' | 'file_audio';
+
+declare type PendingStuckReason = 'pending_too_long' | 'upload_no_progress';
+
+declare type PendingStuckTrackerOptions = Pick<TimedTrackerOptions, 'setTimeout' | 'clearTimeout'>;
+
 declare type PickMessageProps<
 Union,
 T extends Union extends { messageType: infer MT } ? MT : never = Union extends { messageType: infer MT } ? MT : never,
@@ -5115,7 +5659,7 @@ export declare type PositionHorizontal = 'start' | 'end';
 
 export declare type PositionVertical = 'top' | 'bottom';
 
-declare type PresentMethod = 'launcher_toggle' | 'direct_present';
+declare type PresentMethod = 'launcher_toggle' | 'direct_present' | 'embedded';
 
 declare type Props = {
     children: ReactNode;
@@ -5172,6 +5716,120 @@ declare type Props_2 = {
 
 declare type ReactOnlyIconName = 'expand' | 'collapse' | 'chevron-right' | 'attach' | 'close-filled' | 'actionbook' | 'function' | 'confluence' | 'zendesk' | 'salesforce' | 'sprinklr' | 'website' | 'snippet' | 'template' | 'show' | 'mute' | 'activity';
 
+declare type RecoveryMeasurement = {
+    timer: TimeoutId | null;
+    startedAt: number | null;
+    triggerType: RecoveryTriggerType | null;
+    inputEnabled: boolean;
+};
+
+declare class RecoveryNotInteractiveTimeoutStatsTracker {
+    private readonly callback: StatsAppendCallback;
+    private readonly clock: StatsClock;
+    private readonly setTimeoutFn: typeof setTimeout;
+    private readonly clearTimeoutFn: typeof clearTimeout;
+    private readonly measurements = new Map<string, RecoveryMeasurement>();
+
+    constructor(callback: StatsAppendCallback, options?: TimedTrackerOptions) {
+        this.callback = callback;
+        this.clock = getClock(options);
+        this.setTimeoutFn = getSetTimeout(options);
+        this.clearTimeoutFn = getClearTimeout(options);
+    }
+
+    start(triggerType: RecoveryTriggerType, channelUrl?: string): void {
+        const key = this.getKey(channelUrl);
+        let measurement = this.measurements.get(key);
+        if (measurement && measurement.startedAt !== null) return;
+        if (measurement?.inputEnabled) return;
+
+        measurement = {
+            startedAt: this.clock.now(),
+            triggerType,
+            inputEnabled: measurement?.inputEnabled ?? false,
+            timer: this.setTimeoutFn(() => this.commitTimeout(key), 10_000),
+        };
+        this.measurements.set(key, measurement);
+    }
+
+    setInputEnabled(enabled: boolean, channelUrl?: string): void {
+        const key = this.getKey(channelUrl);
+        let measurement = this.measurements.get(key);
+
+        if (!measurement) {
+            if (!enabled) return;
+            measurement = {
+                startedAt: null,
+                triggerType: null,
+                inputEnabled: enabled,
+                timer: null,
+            };
+            this.measurements.set(key, measurement);
+        }
+
+        measurement.inputEnabled = enabled;
+        if (enabled) {
+            this.cancelMeasurement(measurement);
+        }
+    }
+
+    cancelPending(channelUrl: string): void {
+        const key = this.getKey(channelUrl);
+        const measurement = this.measurements.get(key);
+        if (!measurement) return;
+        this.cancelMeasurement(measurement);
+        if (!measurement.inputEnabled) this.measurements.delete(key);
+    }
+
+    clear(): void {
+        this.measurements.forEach((measurement) => clearTimer(measurement.timer, this.clearTimeoutFn));
+        this.measurements.clear();
+    }
+
+    clearChannel(channelUrl?: string): void {
+        if (channelUrl === undefined) return;
+        this.clearKey(this.getKey(channelUrl));
+    }
+
+    private clearKey(key: string): void {
+        const measurement = this.measurements.get(key);
+        if (!measurement) return;
+        clearTimer(measurement.timer, this.clearTimeoutFn);
+        this.measurements.delete(key);
+    }
+
+    private commitTimeout(key: string): void {
+        const measurement = this.measurements.get(key);
+        if (!measurement || measurement.startedAt === null || measurement.triggerType === null) return;
+        if (measurement.inputEnabled) {
+            this.cancelMeasurement(measurement);
+            return;
+        }
+        const duration = this.clock.now() - measurement.startedAt;
+        const triggerType = measurement.triggerType;
+        // Drop the entry so a subsequent trigger can record a fresh cycle.
+        this.measurements.delete(key);
+        append(this.callback, METRIC_KEY_RECOVERY_NOT_INTERACTIVE_TIMEOUT, duration, {
+            extra: {
+                trigger_type: triggerType,
+            },
+        });
+    }
+
+    private cancelMeasurement(measurement: RecoveryMeasurement): void {
+        clearTimer(measurement.timer, this.clearTimeoutFn);
+        measurement.timer = null;
+        measurement.startedAt = null;
+        measurement.triggerType = null;
+    }
+
+    private getKey(channelUrl?: string): string {
+        return channelUrl ?? '__default__';
+    }
+}
+
+declare type RecoveryTriggerType = 'foreground_resume' | 'ws_reconnected';
+
 declare type ReleaseDisabledByValue =
 | 'unavailable'
 | 'form_active'
@@ -5182,6 +5840,39 @@ declare type ReleaseDisabledByValue =
 | 'reconnecting'
 | 'handoff_pending';
 
+declare class RenderedContentUnusableStatsTracker {
+    private readonly callback: StatsAppendCallback;
+    private readonly committed = new Set<string>();
+
+    constructor(callback: StatsAppendCallback) {
+        this.callback = callback;
+    }
+
+    commit(params: {
+        messageId: string | number;
+        contentKind: 'text' | 'image' | 'video' | 'audio' | 'template' | 'form';
+        errorDomain: 'empty_render' | 'template_error' | 'form_error';
+        error?: ErrorLike;
+    }): void {
+        const key = `${params.messageId}:${params.contentKind}:${params.errorDomain}`;
+        if (this.committed.has(key)) return;
+        evictOldestIfAtLimit(this.committed, RENDERED_CONTENT_UNUSABLE_COMMITTED_LIMIT);
+        this.committed.add(key);
+
+        append(this.callback, METRIC_KEY_RENDERED_CONTENT_UNUSABLE, params.errorDomain, {
+            error: params.error ? { code: params.error.code, message: params.errorDomain } : undefined,
+            extra: {
+                content_kind: params.contentKind,
+                message_id: String(params.messageId),
+            },
+        });
+    }
+
+    clear(): void {
+        this.committed.clear();
+    }
+}
+
 declare interface ResolvedHandlers extends AgentClientHandlers {
     onClickLink: (params: {
         url: string;
@@ -5223,6 +5914,15 @@ declare type SingleSelectField = {
 
 declare type StatsAppendCallback = (type: string, data: AIAgentStatPayload) => boolean;
 
+declare interface StatsClock {
+    now: () => number;
+}
+
+declare type StatsPayloadError = {
+    code?: number;
+    message?: string;
+};
+
 /** Per-event override for the platform `announceStatus` wrappers — same shape as `AnnounceOptions`. */
 declare type StatusAnnouncementOptions = AnnounceOptions;
 
@@ -5276,6 +5976,251 @@ declare enum StewardTaskStatus {
     CANCELED = 'CANCELED',
 }
 
+declare class StreamStalledStatsTracker {
+    private readonly callback: StatsAppendCallback;
+    private readonly clock: StatsClock;
+    private readonly setTimeoutFn: typeof setTimeout;
+    private readonly clearTimeoutFn: typeof clearTimeout;
+    private readonly streams = new Map<number, StreamState>();
+    private readonly emittedMessageChannels = new Map<number, string | undefined>();
+
+    constructor(callback: StatsAppendCallback, options?: TimedTrackerOptions) {
+        this.callback = callback;
+        this.clock = getClock(options);
+        this.setTimeoutFn = getSetTimeout(options);
+        this.clearTimeoutFn = getClearTimeout(options);
+    }
+
+    markRawProgress(params: {
+        messageId: number;
+        channelUrl?: string;
+        textLength: number;
+        aiResponse: AIResponseMessageMetadata;
+    }): void {
+        if (!params.aiResponse.isStreaming) {
+            this.completeDelivery(params.messageId, params.textLength);
+            return;
+        }
+
+        if (this.emittedMessageChannels.has(params.messageId)) return;
+
+        const stream = this.getOrCreate(params.messageId, params.channelUrl);
+
+        if (params.textLength > stream.lastRawLength) {
+            stream.chunksReceived += 1;
+            stream.lastRawLength = params.textLength;
+            stream.lastRawAt = this.clock.now();
+
+            clearTimer(stream.deliveryTimer, this.clearTimeoutFn);
+            stream.deliveryTimer = null;
+            this.scheduleDeliveryStallCheck(params.messageId, stream);
+        } else {
+            this.scheduleDeliveryStallCheck(params.messageId, stream);
+        }
+
+        if (stream.lastRenderedLength < stream.lastRawLength && stream.renderTimer === null) {
+            stream.lastRenderAt = this.clock.now();
+            this.scheduleRenderStallCheck(params.messageId, stream, STREAM_RENDER_STALL_THRESHOLD_MS);
+        }
+    }
+
+    markRenderedProgress(params: { messageId: number; displayedLength: number }): void {
+        const stream = this.streams.get(params.messageId);
+        if (!stream || params.displayedLength <= stream.lastRenderedLength) return;
+
+        stream.lastRenderedLength = params.displayedLength;
+        stream.lastRenderAt = this.clock.now();
+
+        if (stream.lastRenderedLength >= stream.lastRawLength) {
+            if (stream.deliveryTimer === null) {
+                this.clearStream(params.messageId, stream);
+                return;
+            }
+
+            clearTimer(stream.renderTimer, this.clearTimeoutFn);
+            stream.renderTimer = null;
+            return;
+        }
+
+        this.scheduleRenderStallCheck(params.messageId, stream, STREAM_RENDER_STALL_THRESHOLD_MS);
+    }
+
+    hasPendingStream(messageId: number): boolean {
+        return this.streams.has(messageId);
+    }
+
+    complete(messageId: number): void {
+        const stream = this.streams.get(messageId);
+        if (stream) this.clearStream(messageId, stream);
+    }
+
+    // Final stream update: no more raw chunks are coming, so stop delivery-stall
+    // tracking. The animation can still be catching up after streaming ends
+    // (useStreamingText keeps animating while displayedLength < text.length), so
+    // keep the render-stall watch alive until rendered progress reaches the last
+    // raw length — otherwise a renderer that freezes mid-catch-up never emits a
+    // 'render' stall.
+    private completeDelivery(messageId: number, finalRawLength: number): void {
+        const stream = this.streams.get(messageId);
+        if (!stream) return;
+
+        // The final stream:false payload can carry text beyond the last streamed
+        // chunk; fold it into the raw length first so the render watch targets the
+        // full text the animation still has to reveal (otherwise the stream could be
+        // cleared while a freeze on that trailing text would go unreported).
+        if (finalRawLength > stream.lastRawLength) {
+            stream.lastRawLength = finalRawLength;
+            stream.lastRawAt = this.clock.now();
+        }
+
+        clearTimer(stream.deliveryTimer, this.clearTimeoutFn);
+        stream.deliveryTimer = null;
+
+        if (stream.lastRenderedLength >= stream.lastRawLength) {
+            this.clearStream(messageId, stream);
+            return;
+        }
+
+        if (stream.renderTimer === null) {
+            stream.lastRenderAt = this.clock.now();
+            this.scheduleRenderStallCheck(messageId, stream, STREAM_RENDER_STALL_THRESHOLD_MS);
+        }
+    }
+
+    clearMessage(messageId: number): void {
+        const stream = this.streams.get(messageId);
+        if (stream) this.clearStream(messageId, stream);
+        this.emittedMessageChannels.delete(messageId);
+    }
+
+    clear(): void {
+        this.streams.forEach((stream) => {
+            clearTimer(stream.deliveryTimer, this.clearTimeoutFn);
+            clearTimer(stream.renderTimer, this.clearTimeoutFn);
+        });
+        this.streams.clear();
+        this.emittedMessageChannels.clear();
+    }
+
+    clearChannel(channelUrl?: string): void {
+        if (!channelUrl) return;
+        this.streams.forEach((stream, messageId) => {
+            if (stream.channelUrl !== channelUrl && stream.channelUrl !== undefined) return;
+            this.clearStream(messageId, stream);
+        });
+        this.emittedMessageChannels.forEach((emittedChannelUrl, messageId) => {
+            if (emittedChannelUrl === channelUrl || emittedChannelUrl === undefined)
+            this.emittedMessageChannels.delete(messageId);
+        });
+    }
+
+    private detectDelivery(messageId: number): void {
+        const stream = this.streams.get(messageId);
+        if (!stream) return;
+        stream.deliveryTimer = null;
+        // Mutex: cancel any in-flight render stall check so delivery wins this turn.
+        clearTimer(stream.renderTimer, this.clearTimeoutFn);
+        stream.renderTimer = null;
+        this.emit(messageId, stream, 'delivery');
+    }
+
+    private detectRender(messageId: number): void {
+        const stream = this.streams.get(messageId);
+        if (!stream) return;
+        stream.renderTimer = null;
+        if (stream.lastRenderedLength >= stream.lastRawLength) return;
+
+        const elapsedSinceRender = this.clock.now() - stream.lastRenderAt;
+        if (elapsedSinceRender < STREAM_RENDER_STALL_THRESHOLD_MS) {
+            this.scheduleRenderStallCheck(messageId, stream, STREAM_RENDER_STALL_THRESHOLD_MS - elapsedSinceRender);
+            return;
+        }
+
+        // Mutex rule: when raw progress has been silent for at least the render threshold,
+        // delivery is the root cause and will win. Defer the render emit until delivery has
+        // had a chance to fire so we don't surface render as the symptom.
+        const elapsedSinceRaw = this.clock.now() - stream.lastRawAt;
+        if (elapsedSinceRaw >= STREAM_RENDER_STALL_THRESHOLD_MS && stream.deliveryTimer !== null) {
+            const untilDelivery = STREAM_DELIVERY_STALL_THRESHOLD_MS - elapsedSinceRaw;
+            if (untilDelivery > 0) {
+                this.scheduleRenderStallCheck(messageId, stream, untilDelivery);
+                return;
+            }
+        }
+
+        this.emit(messageId, stream, 'render');
+    }
+
+    private scheduleRenderStallCheck(messageId: number, stream: StreamState, delayMs: number): void {
+        if (stream.renderTimer !== null) return;
+        stream.renderTimer = this.setTimeoutFn(() => this.detectRender(messageId), delayMs);
+    }
+
+    private scheduleDeliveryStallCheck(messageId: number, stream: StreamState): void {
+        if (stream.deliveryTimer !== null) return;
+        stream.deliveryTimer = this.setTimeoutFn(() => this.detectDelivery(messageId), STREAM_DELIVERY_STALL_THRESHOLD_MS);
+    }
+
+    private emit(messageId: number, stream: StreamState, stallKind: StreamStallKind): void {
+        if (this.emittedMessageChannels.has(messageId)) return;
+
+        const stallStartedAt = stallKind === 'delivery' ? stream.lastRawAt : stream.lastRenderAt;
+        append(this.callback, METRIC_KEY_STREAM_STALLED, this.clock.now() - stallStartedAt, {
+            extra: {
+                message_id: String(messageId),
+                stall_kind: stallKind,
+            },
+        });
+        this.rememberEmitted(messageId, stream.channelUrl);
+        this.clearStream(messageId, stream);
+    }
+
+    private getOrCreate(messageId: number, channelUrl: string | undefined): StreamState {
+        const existing = this.streams.get(messageId);
+        if (existing) return existing;
+
+        const now = this.clock.now();
+        const stream: StreamState = {
+            channelUrl,
+            chunksReceived: 0,
+            lastRawAt: now,
+            lastRenderAt: now,
+            lastRawLength: 0,
+            lastRenderedLength: 0,
+            deliveryTimer: null,
+            renderTimer: null,
+        };
+        this.streams.set(messageId, stream);
+        return stream;
+    }
+
+    private rememberEmitted(messageId: number, channelUrl: string | undefined): void {
+        if (!this.emittedMessageChannels.has(messageId)) {
+            evictOldestIfAtLimit(this.emittedMessageChannels, STREAM_STALLED_EMITTED_LIMIT);
+        }
+        this.emittedMessageChannels.set(messageId, channelUrl);
+    }
+
+    private clearStream(messageId: number, stream: StreamState): void {
+        clearTimer(stream.deliveryTimer, this.clearTimeoutFn);
+        clearTimer(stream.renderTimer, this.clearTimeoutFn);
+        this.streams.delete(messageId);
+    }
+}
+
+declare type StreamStallKind = 'delivery' | 'render';
+
+declare type StreamState = {
+    channelUrl?: string;
+    chunksReceived: number;
+    lastRawAt: number;
+    lastRenderAt: number;
+    lastRawLength: number;
+    lastRenderedLength: number;
+    deliveryTimer: TimeoutId | null;
+    renderTimer: TimeoutId | null;
+};
+
 /**
  * StringSet type for React components
  * Uses SNAKE_CASE keys for backward compatibility
@@ -5550,11 +6495,248 @@ declare type TextField = {
     };
 };
 
+declare type TimedTrackerOptions = TrackerOptions & {
+    setTimeout?: typeof setTimeout;
+    clearTimeout?: typeof clearTimeout;
+};
+
+declare type TimeoutId = ReturnType<typeof setTimeout>;
+
 declare interface TimerData {
     startTime: number | null;
     endTime: number | null;
 }
 
+declare type TrackerOptions = {
+    clock?: StatsClock;
+};
+
+declare class TypingIndicatorAbsentTimeoutStatsTracker {
+    private readonly callback: StatsAppendCallback;
+    private readonly clock: StatsClock;
+    private readonly setTimeoutFn: typeof setTimeout;
+    private readonly clearTimeoutFn: typeof clearTimeout;
+    private readonly turns = new Map<string, TypingTurn>();
+    private readonly pendingAIResponseStartsByUserMessageId = new Map<number, PendingAIResponseStart>();
+
+    constructor(callback: StatsAppendCallback, options?: TimedTrackerOptions) {
+        this.callback = callback;
+        this.clock = getClock(options);
+        this.setTimeoutFn = getSetTimeout(options);
+        this.clearTimeoutFn = getClearTimeout(options);
+    }
+
+    startTurn(params: { requestId: string; channelUrl?: string }): void {
+        this.cancelTurn(params.requestId);
+        const turn: TypingTurn = {
+            requestId: params.requestId,
+            channelUrl: params.channelUrl,
+            beforeTpstStartedAt: this.clock.now(),
+            afterTpenStartedAt: null,
+            timer: null,
+        };
+        turn.timer = this.setTimeoutFn(() => this.commitTimeout(turn.requestId), TYPING_COLLECTION_TIMEOUT_MS);
+        this.turns.set(params.requestId, turn);
+    }
+
+    markUserMessageAck(params: { requestId: string; messageId: number }): void {
+        const turn = this.turns.get(params.requestId);
+        if (!turn) return;
+        turn.userMessageId = params.messageId;
+
+        const pending = this.pendingAIResponseStartsByUserMessageId.get(params.messageId);
+        if (!pending) return;
+        this.pendingAIResponseStartsByUserMessageId.delete(params.messageId);
+        this.applyAIResponseStarted(
+            { channelUrl: pending.channelUrl, matchesUserMessage: true, userMessageId: params.messageId },
+        pending.startedAt,
+        );
+    }
+
+    replaceTurnRequestId(currentRequestId: string, nextRequestId: string): void {
+        if (currentRequestId === nextRequestId) return;
+
+        const turn = this.turns.get(currentRequestId);
+        if (!turn) return;
+
+        this.turns.delete(currentRequestId);
+        turn.requestId = nextRequestId;
+        this.turns.set(nextRequestId, turn);
+    }
+
+    cancelTurn(requestId: string): void {
+        this.cleanupTurn(requestId);
+    }
+
+    markTypingStarted(channelUrl?: string): void {
+        const now = this.clock.now();
+        this.turns.forEach((turn) => {
+            if (!matchesChannel(turn, channelUrl)) return;
+            this.recordAfterTpen(turn, now);
+            this.recordBeforeTpst(turn, now);
+        });
+    }
+
+    markTypingEnded(channelUrl?: string): void {
+        const now = this.clock.now();
+        this.turns.forEach((turn) => {
+            if (!matchesChannel(turn, channelUrl)) return;
+            this.recordBeforeTpst(turn, now);
+            turn.afterTpenStartedAt = now;
+        });
+    }
+
+    markAIResponseStarted(params: { channelUrl?: string; userMessageId?: number } = {}): void {
+        const channelUrl = params.channelUrl;
+        const userMessageId = params.userMessageId;
+        const matchesUserMessage = userMessageId !== undefined;
+        const now = this.clock.now();
+        const matched = this.applyAIResponseStarted({ channelUrl, matchesUserMessage, userMessageId }, now);
+        if (matched || !matchesUserMessage || userMessageId === undefined || !this.hasUnackedTurn(channelUrl)) return;
+
+        if (!this.pendingAIResponseStartsByUserMessageId.has(userMessageId)) {
+            evictOldestIfAtLimit(this.pendingAIResponseStartsByUserMessageId, 100);
+            this.pendingAIResponseStartsByUserMessageId.set(userMessageId, { channelUrl, startedAt: now });
+        }
+    }
+
+    private applyAIResponseStarted(
+    params: { channelUrl?: string; matchesUserMessage: boolean; userMessageId?: number },
+    startedAt: number,
+    ): boolean {
+        if (!params.matchesUserMessage) {
+            const match = this.findSingleTurn(params.channelUrl);
+            if (!match) return false;
+            this.completeTurn(match.requestId, match.turn, startedAt);
+            return true;
+        }
+
+        let matched = false;
+        this.turns.forEach((turn, requestId) => {
+            if (!matchesChannel(turn, params.channelUrl)) return;
+            if (params.matchesUserMessage && turn.userMessageId !== params.userMessageId) return;
+            matched = true;
+            this.completeTurn(requestId, turn, startedAt);
+        });
+        return matched;
+    }
+
+    private findSingleTurn(channelUrl?: string): TypingTurnEntry | undefined {
+        let match: TypingTurnEntry | undefined;
+        let matchedCount = 0;
+        this.turns.forEach((turn, requestId) => {
+            if (!matchesChannel(turn, channelUrl)) return;
+            matchedCount += 1;
+            if (matchedCount > 1) return;
+            match = { requestId, turn };
+        });
+        return matchedCount === 1 ? match : undefined;
+    }
+
+    private completeTurn(requestId: string, turn: TypingTurn, startedAt: number): void {
+        this.recordBeforeTpst(turn, startedAt);
+        this.recordAfterTpen(turn, startedAt);
+        this.commitIfAbsent(requestId, turn);
+    }
+
+    private hasUnackedTurn(channelUrl?: string): boolean {
+        return hasUnackedChannelTurn(this.turns.values(), channelUrl);
+    }
+
+    clear(): void {
+        this.turns.forEach((turn) => {
+            clearTimer(turn.timer, this.clearTimeoutFn);
+        });
+        this.turns.clear();
+        this.pendingAIResponseStartsByUserMessageId.clear();
+    }
+
+    clearChannel(channelUrl?: string): void {
+        if (!channelUrl) return;
+        this.turns.forEach((turn, requestId) => {
+            if (turn.channelUrl !== channelUrl) return;
+            this.cleanupTurn(requestId);
+        });
+        this.pendingAIResponseStartsByUserMessageId.forEach((pending, userMessageId) => {
+            if (pending.channelUrl === channelUrl) this.pendingAIResponseStartsByUserMessageId.delete(userMessageId);
+        });
+    }
+
+    private commitTimeout(requestId: string): void {
+        const turn = this.turns.get(requestId);
+        if (!turn) return;
+        const now = this.clock.now();
+        this.recordBeforeTpst(turn, now);
+        this.recordAfterTpen(turn, now);
+        this.commitIfAbsent(requestId, turn);
+    }
+
+    private recordBeforeTpst(
+    turn: { beforeTpstStartedAt: number | null; beforeTpstAbsentMs?: number },
+    endedAt: number,
+    ): void {
+        if (turn.beforeTpstStartedAt === null) return;
+        const duration = endedAt - turn.beforeTpstStartedAt;
+        if (duration >= TYPING_ABSENT_THRESHOLD_MS) turn.beforeTpstAbsentMs = duration;
+        turn.beforeTpstStartedAt = null;
+    }
+
+    private recordAfterTpen(
+    turn: { afterTpenStartedAt: number | null; afterTpenAbsentMs?: number },
+    endedAt: number,
+    ): void {
+        if (turn.afterTpenStartedAt === null) return;
+        const duration = endedAt - turn.afterTpenStartedAt;
+        if (duration >= TYPING_ABSENT_THRESHOLD_MS) turn.afterTpenAbsentMs = duration;
+        turn.afterTpenStartedAt = null;
+    }
+
+    private commitIfAbsent(requestId: string, turn: { beforeTpstAbsentMs?: number; afterTpenAbsentMs?: number }): void {
+        const beforeTpstAbsentMs = turn.beforeTpstAbsentMs;
+        const afterTpenAbsentMs = turn.afterTpenAbsentMs;
+        if (beforeTpstAbsentMs === undefined && afterTpenAbsentMs === undefined) {
+            this.cleanupTurn(requestId);
+            return;
+        }
+
+        append(
+        this.callback,
+        METRIC_KEY_AI_TYPING_INDICATOR_ABSENT_TIMEOUT,
+        (beforeTpstAbsentMs ?? 0) + (afterTpenAbsentMs ?? 0),
+            {
+            extra: {
+                ...(beforeTpstAbsentMs !== undefined && { before_tpst_absent_ms: beforeTpstAbsentMs }),
+                ...(afterTpenAbsentMs !== undefined && { after_tpen_absent_ms: afterTpenAbsentMs }),
+            },
+        },
+        );
+        this.cleanupTurn(requestId);
+    }
+
+    private cleanupTurn(requestId: string): void {
+        const turn = this.turns.get(requestId);
+        if (!turn) return;
+        clearTimer(turn.timer, this.clearTimeoutFn);
+        this.turns.delete(requestId);
+    }
+}
+
+declare type TypingTurn = {
+    requestId: string;
+    channelUrl?: string;
+    userMessageId?: number;
+    beforeTpstStartedAt: number | null;
+    afterTpenStartedAt: number | null;
+    beforeTpstAbsentMs?: number;
+    afterTpenAbsentMs?: number;
+    timer: TimeoutId | null;
+};
+
+declare type TypingTurnEntry = {
+    requestId: string;
+    turn: TypingTurn;
+};
+
 declare interface TypographyShape {
     h1: TypographyVariant;
     h2: TypographyVariant;
@@ -5630,6 +6812,189 @@ export declare type UserActionStatus =
 
 export declare const useRefreshActiveChannel: (updater: () => Promise<void>) => () => Promise<void>;
 
+declare class UserPerceivedResponseTimeStatsTracker {
+    private readonly callback: StatsAppendCallback;
+    private readonly clock: StatsClock;
+    private readonly random: () => number;
+    private readonly sampledByRequestId = new Map<string, UserTurn>();
+    private readonly sampledByAIMessageId = new Map<number, UserTurn>();
+    private readonly pendingAIResponseByUserMessageId = new Map<number, PendingAIResponseRaw>();
+    private collectedCount = 0;
+
+    constructor(callback: StatsAppendCallback, options?: TrackerOptions & { random?: () => number }) {
+        this.callback = callback;
+        this.clock = getClock(options);
+        this.random = options?.random ?? Math.random;
+    }
+
+    startTurn(params: { requestId: string; channelUrl?: string }): void {
+        if (this.collectedCount >= 10) return;
+        if (this.random() >= 0.15) return;
+        this.collectedCount += 1;
+        this.sampledByRequestId.set(params.requestId, {
+            requestId: params.requestId,
+            channelUrl: params.channelUrl,
+            startedAt: this.clock.now(),
+        });
+    }
+
+    markUserMessageAck(params: { requestId: string; messageId: number }): void {
+        const turn = this.sampledByRequestId.get(params.requestId);
+        if (!turn) return;
+
+        turn.ackAt = this.clock.now();
+        turn.userMessageId = params.messageId;
+
+        const pending = this.pendingAIResponseByUserMessageId.get(params.messageId);
+        if (!pending) return;
+        this.pendingAIResponseByUserMessageId.delete(params.messageId);
+        this.applyAIResponseRaw(turn, pending);
+    }
+
+    replaceTurnRequestId(currentRequestId: string, nextRequestId: string): void {
+        if (currentRequestId === nextRequestId) return;
+
+        const turn = this.sampledByRequestId.get(currentRequestId);
+        if (!turn) return;
+
+        this.sampledByRequestId.delete(currentRequestId);
+        turn.requestId = nextRequestId;
+        this.sampledByRequestId.set(nextRequestId, turn);
+    }
+
+    cancelTurn(requestId: string): void {
+        const turn = this.sampledByRequestId.get(requestId);
+        if (!turn) return;
+        this.deleteTurn(turn);
+        // Return the unused sample slot so cancelled turns don't burn the per-session cap.
+        if (this.collectedCount > 0) this.collectedCount -= 1;
+    }
+
+    markAIResponseRaw(params: { messageId: number; channelUrl?: string; aiResponse: AIResponseMessageMetadata }): void {
+        const firstChunkAt = this.clock.now();
+        const userMessageId = params.aiResponse.userMessageId;
+        if (userMessageId === undefined && this.hasUnackedTurn(params.channelUrl)) return;
+
+        const turn = this.findPendingTurn(params.channelUrl, userMessageId);
+        if (turn) {
+            this.applyAIResponseRaw(turn, { ...params, firstChunkAt });
+            return;
+        }
+
+        if (userMessageId === undefined || !this.hasUnackedTurn(params.channelUrl)) return;
+        this.bufferAIResponseRaw(
+            {
+            messageId: params.messageId,
+            ...(params.channelUrl !== undefined && { channelUrl: params.channelUrl }),
+            aiResponse: params.aiResponse,
+            firstChunkAt,
+        },
+        userMessageId,
+        );
+    }
+
+    markAIResponseVisible(aiMessageId: number): boolean {
+        const turn = this.sampledByAIMessageId.get(aiMessageId);
+        if (!turn || turn.ackAt === undefined || turn.firstChunkAt === undefined || turn.userMessageId === undefined)
+        return false;
+
+        const renderedAt = this.clock.now();
+        append(this.callback, METRIC_KEY_USER_PERCEIVED_RESPONSE_TIME, renderedAt - turn.startedAt, {
+            extra: {
+                ack_to_first_chunk_ms: turn.firstChunkAt - turn.ackAt,
+                first_chunk_to_render_ms: renderedAt - turn.firstChunkAt,
+                is_streaming: Boolean(turn.isStreaming),
+                send_to_ack_ms: turn.ackAt - turn.startedAt,
+            },
+        });
+
+        this.deleteTurn(turn);
+        return true;
+    }
+
+    hasPendingAIResponse(aiMessageId: number): boolean {
+        return this.sampledByAIMessageId.has(aiMessageId);
+    }
+
+    clearMessage(aiMessageId: number): void {
+        this.pendingAIResponseByUserMessageId.forEach((pending, userMessageId) => {
+            if (pending.messageId === aiMessageId) this.pendingAIResponseByUserMessageId.delete(userMessageId);
+        });
+
+        const turn = this.sampledByAIMessageId.get(aiMessageId);
+        if (!turn) return;
+
+        this.deleteTurn(turn);
+        if (this.collectedCount > 0) this.collectedCount -= 1;
+    }
+
+    clearChannel(channelUrl?: string): void {
+        if (!channelUrl) return;
+        this.sampledByRequestId.forEach((turn) => {
+            if (turn.channelUrl !== channelUrl) return;
+            this.deleteTurn(turn);
+            if (this.collectedCount > 0) this.collectedCount -= 1;
+        });
+        this.pendingAIResponseByUserMessageId.forEach((pending, userMessageId) => {
+            if (pending.channelUrl === channelUrl) this.pendingAIResponseByUserMessageId.delete(userMessageId);
+        });
+    }
+
+    clear(): void {
+        this.sampledByRequestId.clear();
+        this.sampledByAIMessageId.clear();
+        this.pendingAIResponseByUserMessageId.clear();
+        this.collectedCount = 0;
+    }
+
+    private findPendingTurn(channelUrl?: string, userMessageId?: number): UserTurn | undefined {
+        if (userMessageId !== undefined) {
+            for (const turn of this.sampledByRequestId.values()) {
+                if (turn.ackAt === undefined || turn.firstChunkAt !== undefined) continue;
+                if (!matchesChannel(turn, channelUrl)) continue;
+                if (turn.userMessageId === userMessageId) return turn;
+            }
+            return undefined;
+        }
+
+        let match: UserTurn | undefined;
+        for (const turn of this.sampledByRequestId.values()) {
+            if (turn.ackAt === undefined || turn.firstChunkAt !== undefined) continue;
+            if (!matchesChannel(turn, channelUrl)) continue;
+            if (match) return undefined;
+            match = turn;
+        }
+        return match;
+    }
+
+    private applyAIResponseRaw(turn: UserTurn, params: PendingAIResponseRaw): void {
+        if (turn.firstChunkAt !== undefined) return;
+
+        turn.firstChunkAt = turn.ackAt === undefined ? params.firstChunkAt : Math.max(params.firstChunkAt, turn.ackAt);
+        turn.aiMessageId = params.messageId;
+        turn.channelUrl = turn.channelUrl ?? params.channelUrl;
+        turn.isStreaming = params.aiResponse.isStreaming;
+        this.sampledByAIMessageId.set(params.messageId, turn);
+    }
+
+    private bufferAIResponseRaw(params: PendingAIResponseRaw, userMessageId: number): void {
+        if (!this.pendingAIResponseByUserMessageId.has(userMessageId)) {
+            evictOldestIfAtLimit(this.pendingAIResponseByUserMessageId, 100);
+            this.pendingAIResponseByUserMessageId.set(userMessageId, params);
+        }
+    }
+
+    private hasUnackedTurn(channelUrl?: string): boolean {
+        return hasUnackedChannelTurn(this.sampledByRequestId.values(), channelUrl);
+    }
+
+    private deleteTurn(turn: UserTurn): void {
+        this.sampledByRequestId.delete(turn.requestId);
+        if (turn.aiMessageId !== undefined) this.sampledByAIMessageId.delete(turn.aiMessageId);
+        if (turn.userMessageId !== undefined) this.pendingAIResponseByUserMessageId.delete(turn.userMessageId);
+    }
+}
+
 /**
  * User session containing authentication credentials.
  */
@@ -5647,6 +7012,17 @@ declare interface UserSessionInfo {
     sessionHandler: AIAgentSessionHandler;
 }
 
+declare type UserTurn = {
+    requestId: string;
+    channelUrl?: string;
+    startedAt: number;
+    ackAt?: number;
+    firstChunkAt?: number;
+    userMessageId?: number;
+    aiMessageId?: number;
+    isStreaming?: boolean;
+};
+
 export { }