agora-appbuilder-core 4.1.26 → 4.1.27-beta.2

package/template/src/atoms/CustomIcon.tsx

@@ -155,4 +155,5 @@ export interface IconsInterface {
   fullscreen: string;
   add_reaction: string;
   spotlight: string;
+  'agent-bot': string;
 }

package/template/src/logger/AppBuilderLogger.tsx

@@ -38,6 +38,8 @@ export declare const StatusTypes: {
 
 export type StatusType = (typeof StatusTypes)[keyof typeof StatusTypes];
 
+export type CustomizationLogType = string;
+
 export enum LogSource {
   AgoraSDK = 'Agora-SDK',
   /** Logs related to all features */
@@ -107,10 +109,7 @@ type LogType = {
     | 'recording_delete'
     | 'ban_user';
   [LogSource.Events]: 'CUSTOM_EVENTS' | 'RTM_EVENTS';
-  [LogSource.CustomizationAPI]:
-    | 'Log'
-    | 'AI_AGENT_CUSTOMIZATION'
-    | 'EXTERNAL_CUSTOMIZATION';
+  [LogSource.CustomizationAPI]: CustomizationLogType;
   [LogSource.SDK]: 'Log' | 'Event';
 };
 

package/template/src/subComponents/caption/Transcript.tsx

@@ -23,6 +23,8 @@ import {
 import {TranscriptHeader} from '../../pages/video-call/SidePanelHeader';
 import {useContent} from 'customization-api';
 import {TranscriptItem, useCaption} from './useCaption';
+import {logger, LogSource} from '../../logger/AppBuilderLogger';
+import {TRANSCRIPT_JOURNEY} from './transcriptJourney';
 import {TranscriptText} from './TranscriptText';
 import PrimaryButton from '../../atoms/PrimaryButton';
 import ThemeConfig from '../../theme';
@@ -54,6 +56,7 @@ const Transcript = (props: TranscriptProps) => {
     isLangChangeInProgress,
     getBotOwnerUid,
     isSTTActive,
+    isSTTListenerAdded,
     selectedTranslationLanguage,
     transcriptViewMode,
   } = useCaption();
@@ -69,6 +72,40 @@ const Transcript = (props: TranscriptProps) => {
   const data = meetingTranscript; // Object.entries(transcript);
   console.log('[STT_GLOBAL] meetingTranscript data: ', data);
 
+  const hasLoggedFirstEntryRef = React.useRef(false);
+  const transcriptEntryCountRef = React.useRef(data.length);
+  transcriptEntryCountRef.current = data.length;
+
+  React.useEffect(() => {
+    logger.log(
+      LogSource.Internals,
+      'TRANSCRIPT',
+      `${TRANSCRIPT_JOURNEY} transcript panel state`,
+      {
+        stage: 'transcript_panel',
+        isSTTActive,
+        listenerRegistered: isSTTListenerAdded,
+        transcriptEntryCount: transcriptEntryCountRef.current,
+      },
+    );
+  }, [isSTTActive, isSTTListenerAdded]);
+
+  React.useEffect(() => {
+    if (data.length > 0 && !hasLoggedFirstEntryRef.current) {
+      hasLoggedFirstEntryRef.current = true;
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} first transcript entry available to panel`,
+        {
+          stage: 'transcript_panel_data',
+          outcome: 'success',
+          transcriptEntryCount: data.length,
+        },
+      );
+    }
+  }, [data.length]);
+
   const [showButton, setShowButton] = React.useState(false);
 
   const contentHeightRef = React.useRef(0);

package/template/src/subComponents/caption/__tests__/transcriptJourney.test.ts

@@ -0,0 +1,7 @@
+import {TRANSCRIPT_JOURNEY} from '../transcriptJourney';
+
+describe('transcript journey logging', () => {
+  it('uses one searchable prefix', () => {
+    expect(TRANSCRIPT_JOURNEY).toBe('[TRANSCRIPT_JOURNEY]');
+  });
+});

package/template/src/subComponents/caption/useCaption.tsx

@@ -625,22 +625,21 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
     try {
       setIsLangChangeInProgress(true);
       const result = await start(localBotUidRef.current, newConfig);
-      console.log('[STT] start result: ', result);
       if (result.success) {
         setIsSTTError(false);
         logger.log(
           LogSource.NetworkRest,
           'stt',
-          'STT started successfully',
-          result.data,
+          `${TRANSCRIPT_JOURNEY} STT started successfully`,
+          result.data ?? null,
         );
       } else {
         setIsSTTError(true);
         logger.error(
           LogSource.NetworkRest,
           'stt',
-          'Failed to start STT',
-          result.error,
+          `${TRANSCRIPT_JOURNEY} failed to start STT`,
+          result.error ?? null,
         );
         Toast.show({
           leadingIconName: 'alert',
@@ -657,7 +656,12 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
     } catch (error: any) {
       setIsLangChangeInProgress(false);
       setIsSTTError(true);
-      logger.error(LogSource.NetworkRest, 'stt', 'STT start error', error);
+      logger.error(
+        LogSource.NetworkRest,
+        'stt',
+        `${TRANSCRIPT_JOURNEY} STT start error`,
+        error ?? null,
+      );
       // Show error toast: text1 = translated label, text2 = exception error
       Toast.show({
         leadingIconName: 'alert',
@@ -702,16 +706,16 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
         logger.log(
           LogSource.NetworkRest,
           'stt',
-          'STT updated successfully',
-          result.data,
+          `${TRANSCRIPT_JOURNEY} STT updated successfully`,
+          result.data ?? null,
         );
       } else {
         setIsSTTError(true);
         logger.error(
           LogSource.NetworkRest,
           'stt',
-          'Failed to update STT',
-          result.error,
+          `${TRANSCRIPT_JOURNEY} failed to update STT`,
+          result.error ?? null,
         );
         // Show error toast: text1 = translated label, text2 = API error
         Toast.show({
@@ -729,7 +733,12 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
     } catch (error: any) {
       setIsLangChangeInProgress(false);
       setIsSTTError(true);
-      logger.error(LogSource.NetworkRest, 'stt', 'STT update error', error);
+      logger.error(
+        LogSource.NetworkRest,
+        'stt',
+        `${TRANSCRIPT_JOURNEY} STT update error`,
+        error ?? null,
+      );
       // Show error toast: text1 = translated label, text2 = exception error
       Toast.show({
         leadingIconName: 'alert',
@@ -748,10 +757,20 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
   };
 
   const stopSTTBotSession = React.useCallback(async () => {
-    console.log('[STT] stopSTTBotSession called');
+    logger.log(
+      LogSource.Internals,
+      'TRANSCRIPT',
+      `${TRANSCRIPT_JOURNEY} STT stop requested`,
+      {stage: 'stt_stop', localBotUid: localBotUidRef.current ?? null},
+    );
 
     if (!localBotUidRef.current) {
-      console.warn('[STT] Missing botUid for stop');
+      logger.warn(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} STT stop skipped because bot UID is missing`,
+        {stage: 'stt_stop', outcome: 'skipped'},
+      );
       return;
     }
 
@@ -767,16 +786,16 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
         logger.log(
           LogSource.NetworkRest,
           'stt',
-          'STT stopped successfully',
-          result.data,
+          `${TRANSCRIPT_JOURNEY} STT stopped successfully`,
+          result.data ?? null,
         );
       } else {
         setIsSTTError(true);
         logger.error(
           LogSource.NetworkRest,
           'stt',
-          'Failed to stop STT',
-          result.error,
+          `${TRANSCRIPT_JOURNEY} failed to stop STT`,
+          result.error ?? null,
         );
       }
     } catch (error) {
@@ -784,8 +803,8 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
       logger.error(
         LogSource.NetworkRest,
         'stt',
-        'Error in stopSTTBotSession',
-        error,
+        `${TRANSCRIPT_JOURNEY} error in stopSTTBotSession`,
+        error ?? null,
       );
     }
   }, [stop]);
@@ -856,12 +875,29 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
         // Queue
         enqueueSttEvent(updatedState, true, targetChange);
 
-        console.log(
-          '[STT_GLOBAL] confirmSpokenLanguageChange sent STT_GLOBAL_STATE: ',
-          updatedState,
+        logger.log(
+          LogSource.Internals,
+          'TRANSCRIPT',
+          `${TRANSCRIPT_JOURNEY} local spoken-language state queued`,
+          {
+            stage: 'global_state_queue',
+            outcome: 'queued',
+            spokenLanguage: updatedState.globalSpokenLanguage ?? null,
+            translationTargetCount:
+              updatedState.globalTranslationTargets.length,
+          },
         );
       } catch (error) {
-        console.log('[STT_GLOBAL] confirmSpokenLanguageChange error: ', error);
+        logger.error(
+          LogSource.Internals,
+          'TRANSCRIPT',
+          `${TRANSCRIPT_JOURNEY} local spoken-language state failed`,
+          {
+            stage: 'global_state_queue',
+            outcome: 'failure',
+            error: error ?? null,
+          },
+        );
       }
     },
     [localUid], // only real dependency
@@ -916,15 +952,24 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
   // Queues all local + remote stt events
   const enqueueSttEvent = React.useCallback(
     (state: GlobalSttState, isLocal: boolean, targetChange?: TargetChange) => {
-      console.log(
-        '[STT_GLOBAL] inside enqueueSttEvent - sttDepsReadyRef flag',
-        sttDepsReadyRef.current,
-      );
       sttEventQueueRef.current.push({
         state,
         isLocal,
         targetChange,
       });
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} STT global state queued`,
+        {
+          stage: 'global_state_queue',
+          outcome: 'queued',
+          stateOrigin: isLocal ? 'local' : 'remote',
+          sttEnabled: state.globalSttEnabled,
+          sttDepsReady: sttDepsReadyRef.current,
+          queueSize: sttEventQueueRef.current.length,
+        },
+      );
       if (sttDepsReadyRef.current) {
         processSttEventQueue();
       }
@@ -951,7 +996,12 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
         !globalSttStateRef.current.globalSttEnabled &&
         sttEventQueueRef.current.length === 0
       ) {
-        console.log('[STT] AUTO_START  injecting auto start state');
+        logger.log(
+          LogSource.Internals,
+          'TRANSCRIPT',
+          `${TRANSCRIPT_JOURNEY} STT auto-start state injected`,
+          {stage: 'global_state_queue', outcome: 'queued'},
+        );
 
         sttAutoStartGuardRef.current = true;
 
@@ -978,7 +1028,12 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
       const {state: newState, isLocal, targetChange} = item;
       const prevState = globalSttStateRef.current;
       if (isSameState(prevState, newState)) {
-        console.log('[STT] Skipped duplicate STT_GLOBAL_STATE');
+        logger.log(
+          LogSource.Internals,
+          'TRANSCRIPT',
+          `${TRANSCRIPT_JOURNEY} duplicate STT global state skipped`,
+          {stage: 'global_state_queue', outcome: 'skipped'},
+        );
         continue; // no call to processGlobalSttSingleEvent
       }
       const ok = await processGlobalSttSingleEvent(
@@ -988,16 +1043,22 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
       );
       if (!ok) {
         if (isLocal) {
-          console.warn(
-            '[STT] Skipping local global state update because API failed.',
+          logger.warn(
+            LogSource.Internals,
+            'TRANSCRIPT',
+            `${TRANSCRIPT_JOURNEY} local global state update skipped because API failed`,
+            {stage: 'global_state_apply', outcome: 'skipped'},
           );
           continue;
         }
         // A received RTM event is authoritative for the meeting-level state.
         // Failure to provision this participant's bot must not make the UI
         // report that meeting STT is disabled while captions are arriving.
-        console.warn(
-          '[STT] Applying remote global state after local STT API failure.',
+        logger.warn(
+          LogSource.Internals,
+          'TRANSCRIPT',
+          `${TRANSCRIPT_JOURNEY} remote global state applied after local STT API failure`,
+          {stage: 'global_state_apply', outcome: 'applied_with_api_failure'},
         );
       }
       // update global state AFTER processing
@@ -1022,10 +1083,24 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
       const isStopOperation = wasEnabledBefore && !isEnabledNow;
       try {
         if (isStartOperation) {
-          console.log('[STT] Remote global STT -> starting session', newState);
+          logger.log(
+            LogSource.Internals,
+            'TRANSCRIPT',
+            `${TRANSCRIPT_JOURNEY} STT global state selected start operation`,
+            {
+              stage: 'global_state_operation',
+              outcome: 'started',
+              stateOrigin: isLocal ? 'local' : 'remote',
+            },
+          );
           // Start guard starts
           if (sttStartGuardRef.current) {
-            console.log('[STT] Start skipped (already started)');
+            logger.log(
+              LogSource.Internals,
+              'TRANSCRIPT',
+              `${TRANSCRIPT_JOURNEY} STT start skipped by start guard`,
+              {stage: 'global_state_operation', outcome: 'skipped'},
+            );
             return;
           }
           sttStartGuardRef.current = true;
@@ -1096,7 +1171,16 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
           }
           return true;
         } else if (isUpdateOperation) {
-          console.log('[STT] Global STT -> updating session', newState);
+          logger.log(
+            LogSource.Internals,
+            'TRANSCRIPT',
+            `${TRANSCRIPT_JOURNEY} STT global state selected update operation`,
+            {
+              stage: 'global_state_operation',
+              outcome: 'started',
+              stateOrigin: isLocal ? 'local' : 'remote',
+            },
+          );
           const result = await updateSTTBotSession(
             {
               source: [newState.globalSpokenLanguage],
@@ -1160,7 +1244,16 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
           }
           return true;
         } else if (isStopOperation) {
-          console.log('[STT] Global STT -> stopping session', newState);
+          logger.log(
+            LogSource.Internals,
+            'TRANSCRIPT',
+            `${TRANSCRIPT_JOURNEY} STT global state selected stop operation`,
+            {
+              stage: 'global_state_operation',
+              outcome: 'started',
+              stateOrigin: isLocal ? 'local' : 'remote',
+            },
+          );
           await stopSTTBotSession();
           sttStartGuardRef.current = false;
           return true;
@@ -1173,8 +1266,8 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
         logger.error(
           LogSource.Internals,
           'STT',
-          'Error handling STT_GLOBAL_STATE event',
-          error,
+          `${TRANSCRIPT_JOURNEY} error handling STT_GLOBAL_STATE event`,
+          error ?? null,
         );
         return false;
       }
@@ -1186,7 +1279,16 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
   React.useEffect(() => {
     const handleGlobalSTTChange = async (evt: any) => {
       const {payload} = evt || {};
-      console.log('[STT] STT_GLOBAL_STATE event received: ', evt);
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} STT_GLOBAL_STATE event received`,
+        {
+          stage: 'global_state_event',
+          outcome: 'received',
+          payloadPresent: typeof payload === 'string' && payload.length > 0,
+        },
+      );
       let newState: GlobalSttState;
       try {
         newState = JSON.parse(payload);
@@ -1194,8 +1296,8 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
         logger.error(
           LogSource.Internals,
           'STT',
-          'Failed to parse STT_GLOBAL_STATE event payload',
-          error,
+          `${TRANSCRIPT_JOURNEY} failed to parse STT_GLOBAL_STATE event payload`,
+          error ?? null,
         );
         return;
       }

package/template/src/subComponents/caption/useSTTAPI.tsx

@@ -7,6 +7,7 @@ import {logger, LogSource} from '../../logger/AppBuilderLogger';
 import getUniqueID from '../../utils/getUniqueID';
 import {buildSTTRequestBody, type STTMethod} from './sttRequestBody';
 import {ensureSTTSessionId} from './sttSessionId';
+import {TRANSCRIPT_JOURNEY} from './transcriptJourney';
 
 export interface STTAPIResponse {
   success: boolean;
@@ -99,12 +100,12 @@ const useSTTAPI = (): IuseSTTAPI => {
       });
 
       console.log(
-        `[STT_BOT_SUBSCRIPTION] ${method.toUpperCase()} - Bot UID: ${botUid} will subscribe to User UID: ${ownerUid}`,
+        `${TRANSCRIPT_JOURNEY} [STT_BOT_SUBSCRIPTION] ${method.toUpperCase()} - Bot UID: ${botUid} will subscribe to User UID: ${ownerUid}`,
         {
           method,
           botUid,
           ownerUid,
-          translationConfig,
+          translationConfig: translationConfig ?? null,
         },
       );
       const response = await fetch(`${STT_API_URL}/${method}`, {
@@ -146,10 +147,10 @@ const useSTTAPI = (): IuseSTTAPI => {
         logger.error(
           LogSource.NetworkRest,
           'stt',
-          `STT API Failure - Called ${method}`,
-          errorPayload,
+          `${TRANSCRIPT_JOURNEY} STT API Failure - Called ${method}`,
+          errorPayload ?? {message},
           {
-            responseData: res,
+            responseData: res ?? null,
             httpStatus,
             requestId,
             startReqTs,
@@ -172,9 +173,9 @@ const useSTTAPI = (): IuseSTTAPI => {
       logger.log(
         LogSource.NetworkRest,
         'stt',
-        `STT API Success - Called ${method}`,
+        `${TRANSCRIPT_JOURNEY} STT API Success - Called ${method}`,
         {
-          responseData: res,
+          responseData: res ?? null,
           httpStatus,
           requestId,
           startReqTs,
@@ -194,8 +195,8 @@ const useSTTAPI = (): IuseSTTAPI => {
       logger.error(
         LogSource.NetworkRest,
         'stt',
-        `STT API Failure - Called ${method}`,
-        error,
+        `${TRANSCRIPT_JOURNEY} STT API Failure - Called ${method}`,
+        error ?? null,
         {
           requestId,
           startReqTs,
@@ -235,14 +236,14 @@ const useSTTAPI = (): IuseSTTAPI => {
       logger.log(
         LogSource.NetworkRest,
         'stt',
-        'Retrying STT start after transient failure',
+        `${TRANSCRIPT_JOURNEY} Retrying STT start after transient failure`,
         {
           attempt,
           maxAttempts: STT_START_MAX_ATTEMPTS,
           retryDelayMs,
           botUid,
-          httpStatus: result.httpStatus,
-          errorCode: result.error?.code,
+          httpStatus: result.httpStatus ?? null,
+          errorCode: result.error?.code ?? null,
         },
       );
       await wait(retryDelayMs);

package/template/src/subComponents/caption/useStreamMessageUtils.ts

@@ -3,6 +3,8 @@ import protoRoot from './proto/ptoto';
 import PQueue from 'p-queue';
 import type {CaptionObj, TranscriptItem} from './useCaption';
 import type {LanguageType} from './utils';
+import {logger, LogSource} from '../../logger/AppBuilderLogger';
+import {TRANSCRIPT_JOURNEY} from './transcriptJourney';
 
 type StreamMessageCallback = (args: [number, Uint8Array]) => void;
 type FinalListType = {
@@ -42,8 +44,29 @@ const useStreamMessageUtils = ({
   const finalTranscriptListRef = React.useRef<FinalListType>({});
   const finalTranslationListRef = React.useRef<FinalTranslationListType>({});
   const queue = React.useMemo(() => new PQueue({concurrency: 1}), []);
+  const messagesReceivedRef = React.useRef(0);
+  const messagesProcessedRef = React.useRef(0);
+  const finalizedSegmentsRef = React.useRef(0);
+  const speakersWithFinalizedSegmentsRef = React.useRef(new Set<string>());
 
   const streamMessageCallback: StreamMessageCallback = args => {
+    const [receivedBotUid, receivedPayload] = args;
+    const messageNumber = ++messagesReceivedRef.current;
+    if (messageNumber === 1 || messageNumber % 50 === 0) {
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} stream message received`,
+        {
+          stage: 'stream_message_received',
+          outcome: 'success',
+          botUid: receivedBotUid ?? null,
+          payloadByteLength: receivedPayload?.byteLength || 0,
+          messagesReceived: messageNumber,
+          messagesProcessed: messagesProcessedRef.current,
+        },
+      );
+    }
     const queueCallback = (args1: [number, Uint8Array]) => {
       const finalList = finalListRef.current;
       const finalTranscriptList = finalTranscriptListRef.current;
@@ -221,11 +244,29 @@ const useStreamMessageUtils = ({
         finalList[textstream.uid].push(finalText);
         finalTranscriptList[textstream.uid].push(finalText);
         currentFinalText = finalText;
-        // log info to show measure the duration of passes in which a sentence gets finalized
+        const speakerUid = textstream.uid ?? null;
+        const speakerKey = String(speakerUid ?? 'unknown');
+        const isFirstFinalizedSegmentForSpeaker =
+          !speakersWithFinalizedSegmentsRef.current.has(speakerKey);
+        finalizedSegmentsRef.current += 1;
         const duration = performance.now() - captionStartTimeRef.current;
-        console.log(
-          `stt-Time taken to finalize caption ${currentFinalText}: ${duration}ms`,
-        );
+        if (isFirstFinalizedSegmentForSpeaker) {
+          speakersWithFinalizedSegmentsRef.current.add(speakerKey);
+          logger.log(
+            LogSource.Internals,
+            'TRANSCRIPT',
+            `${TRANSCRIPT_JOURNEY} first transcript segment finalized for speaker`,
+            {
+              stage: 'segment_finalized',
+              outcome: 'success',
+              botUid: botUid ?? null,
+              speakerUid,
+              finalCharacterCount: currentFinalText.length,
+              finalizeDurationMs: duration,
+              finalizedSegments: finalizedSegmentsRef.current,
+            },
+          );
+        }
         captionStartTimeRef.current = 0; // Reset start time
       }
 
@@ -364,14 +405,74 @@ const useStreamMessageUtils = ({
     };
     void queue
       .add(() => queueCallback(args))
-      .then(() => console.log('stt- using pq queue'))
-      .catch(error =>
-        console.error('Failed to process STT stream message', error),
-      );
+      .then(() => {
+        const processedCount = ++messagesProcessedRef.current;
+        if (processedCount === 1 || processedCount % 50 === 0) {
+          logger.log(
+            LogSource.Internals,
+            'TRANSCRIPT',
+            `${TRANSCRIPT_JOURNEY} stream message processed`,
+            {
+              stage: 'stream_message_processed',
+              outcome: 'success',
+              botUid: receivedBotUid ?? null,
+              messagesReceived: messagesReceivedRef.current,
+              messagesProcessed: processedCount,
+              queueSize: queue.size,
+            },
+          );
+        }
+      })
+      .catch(error => {
+        logger.error(
+          LogSource.Internals,
+          'TRANSCRIPT',
+          `${TRANSCRIPT_JOURNEY} failed to process stream message`,
+          {
+            stage: 'stream_message_processing',
+            outcome: 'failure',
+            botUid: receivedBotUid ?? null,
+            messageNumber,
+            messagesReceived: messagesReceivedRef.current,
+            messagesProcessed: messagesProcessedRef.current,
+            error: error ?? null,
+          },
+        );
+      });
   };
 
   const flushStreamMessageQueue = React.useCallback(async () => {
+    logger.log(
+      LogSource.Internals,
+      'TRANSCRIPT',
+      `${TRANSCRIPT_JOURNEY} stream queue flush requested`,
+      {
+        stage: 'stream_queue_flush',
+        outcome: 'started',
+        messagesReceived: messagesReceivedRef.current,
+        messagesProcessed: messagesProcessedRef.current,
+        finalizedSegments: finalizedSegmentsRef.current,
+        speakersWithFinalizedSegments:
+          speakersWithFinalizedSegmentsRef.current.size,
+        queueSize: queue.size,
+      },
+    );
     await queue.onIdle();
+    logger.log(
+      LogSource.Internals,
+      'TRANSCRIPT',
+      `${TRANSCRIPT_JOURNEY} stream queue flush completed`,
+      {
+        stage: 'stream_queue_flush',
+        outcome: 'success',
+        messagesReceived: messagesReceivedRef.current,
+        messagesProcessed: messagesProcessedRef.current,
+        finalizedSegments: finalizedSegmentsRef.current,
+        speakersWithFinalizedSegments:
+          speakersWithFinalizedSegmentsRef.current.size,
+        queueSize: queue.size,
+      },
+    );
   }, [queue]);
 
   return {