botium-connector-voip 0.0.23 → 0.0.25

package/dist/botium-connector-voip-cjs.js

@@ -49,6 +49,7 @@ const Capabilities = {
   VOIP_STT_TIMEOUT: 'VOIP_STT_TIMEOUT',
   VOIP_STT_MESSAGE_HANDLING: 'VOIP_STT_MESSAGE_HANDLING',
   VOIP_STT_MESSAGE_HANDLING_TIMEOUT: 'VOIP_STT_MESSAGE_HANDLING_TIMEOUT',
+  VOIP_STT_MESSAGE_HANDLING_TIMEOUT_SUBSEQUENT: 'VOIP_STT_MESSAGE_HANDLING_TIMEOUT_SUBSEQUENT',
   VOIP_STT_MESSAGE_HANDLING_DELIMITER: 'VOIP_STT_MESSAGE_HANDLING_DELIMITER',
   VOIP_STT_MESSAGE_HANDLING_PUNCTUATION: 'VOIP_STT_MESSAGE_HANDLING_PUNCTUATION',
   VOIP_TTS_URL: 'VOIP_TTS_URL',
@@ -87,7 +88,8 @@ const Capabilities = {
   VOIP_SILENCE_DURATION_TIMEOUT_START: 'VOIP_SILENCE_DURATION_TIMEOUT_START',
   VOIP_STT_CONFIDENCE_THRESHOLD: 'VOIP_STT_CONFIDENCE_THRESHOLD',
   VOIP_USE_GLOBAL_VOIP_WORKER: 'VOIP_USE_GLOBAL_VOIP_WORKER',
-  VOIP_USER_INPUT_PREFER_VOICE: 'VOIP_USER_INPUT_PREFER_VOICE'
+  VOIP_USER_INPUT_PREFER_VOICE: 'VOIP_USER_INPUT_PREFER_VOICE',
+  VOIP_EMIT_SPECULATIVE_TEXT: 'VOIP_EMIT_SPECULATIVE_TEXT'
 };
 const Defaults = {
   VOIP_STT_METHOD: 'POST',
@@ -139,6 +141,7 @@ class BotiumConnectorVoip {
     // For debugging latency between incoming STT (bot says) and outgoing audio (sendAudio)
     this._lastBotSaysQueuedAt = null;
     this._lastBotSaysText = null;
+    this._speculativeTurnToken = 0;
   }
   async Validate() {
     debug$3('Validate called');
@@ -189,8 +192,20 @@ class BotiumConnectorVoip {
       this.ttsCache.clear();
     }
     const sendBotMsg = botMsg => {
-      this._lastBotSaysQueuedAt = Date.now();
+      const queuedAt = Date.now();
+      this._lastBotSaysQueuedAt = queuedAt;
       this._lastBotSaysText = botMsg && botMsg.messageText ? String(botMsg.messageText) : null;
+      // Stamp the wall-clock instant at which the connector released the bot
+      // utterance to botium-core's queue. Paired with `_receivedAtMs` (last
+      // STT final frame) this gives the true "join silence" the connector
+      // imposed, independent of how long the coach later takes to pick the
+      // message up with WaitBotSays().
+      if (botMsg && botMsg.sourceData) {
+        const head = Array.isArray(botMsg.sourceData) ? botMsg.sourceData[0] : botMsg.sourceData;
+        if (head && typeof head === 'object' && !('flushedAtMs' in head)) {
+          head.flushedAtMs = queuedAt;
+        }
+      }
       setTimeout(() => this.queueBotSays(botMsg), 0);
     };
     const joinBotMsg = (botMsgs, joinLastPrevMsg) => {
@@ -211,6 +226,161 @@ class BotiumConnectorVoip {
       }
       return botMsg;
     };
+
+    // Returns true when a partial represents a NEW utterance rather than a tail/echo
+    // of buffered text. Used by PSST partial handler to extend the silence timer.
+    // Heuristic: substring check, then word-overlap fallback (<70% overlap = new).
+    const partialLooksLikeNewUtterance = (partialText, botMsgs) => {
+      const normalize = s => String(s || '').toLowerCase().replace(/[^a-z0-9\s]/g, ' ').replace(/\s+/g, ' ').trim();
+      const partial = normalize(partialText);
+      if (!partial) return false;
+      const buffered = normalize((botMsgs || []).map(m => m && m.messageText || '').join(' '));
+      if (!buffered) return true;
+      if (buffered.includes(partial)) return false;
+      const partialWords = partial.split(' ').filter(Boolean);
+      if (partialWords.length === 0) return false;
+      const bufferedWords = new Set(buffered.split(' ').filter(Boolean));
+      const overlap = partialWords.filter(w => bufferedWords.has(w)).length;
+      return overlap / partialWords.length < 0.7;
+    };
+
+    // Arm (or re-arm) the JOIN/PSST silence timer that flushes buffered STT
+    // chunks once the bot has been silent for `joinTimeoutMs`. No-op outside
+    // JOIN/PSST/CONCAT modes (other modes emit finals immediately).
+    const armJoinSilenceTimer = () => {
+      if (!this.botMsgs || this.botMsgs.length === 0) return;
+      const sttHandling = this.caps[Capabilities.VOIP_STT_MESSAGE_HANDLING];
+      const joinLogicHook = this._getJoinLogicHook(this.convoStep);
+      const isJoinMethod = sttHandling === 'JOIN' || sttHandling === 'PSST' || sttHandling === 'CONCAT' || !lodash__default["default"].isNil(joinLogicHook);
+      if (!isJoinMethod) return;
+      const isPsst = sttHandling === 'PSST';
+      const toJoinTimeoutMs = ms => {
+        const parsed = parseInt(ms, 10);
+        if (!lodash__default["default"].isFinite(parsed) || parsed <= 0) return null;
+        return isPsst ? Math.max(0, parsed - 500) : parsed;
+      };
+      let joinTimeoutMs = toJoinTimeoutMs(lodash__default["default"].get(joinLogicHook, 'args[0]'));
+      if (!lodash__default["default"].isFinite(joinTimeoutMs) || joinTimeoutMs <= 0) {
+        joinTimeoutMs = toJoinTimeoutMs(this._getEffectiveMessageHandlingTimeout());
+      }
+      if (this.silenceTimeout) {
+        clearTimeout(this.silenceTimeout);
+        this.silenceTimeout = null;
+      }
+      const bufferedAtArm = this.botMsgs.length;
+      const armedAt = Date.now();
+      _info('psst_timer_armed', {
+        sessionId: this.sessionId,
+        joinTimeoutMs: joinTimeoutMs || 0,
+        bufferedChunks: bufferedAtArm,
+        stopCalled: !!this.stopCalled
+      });
+      // Emit the authoritative join timeout so downstream consumers (e.g.
+      // SpeculationBuffer) can size their quiet threshold relative to it.
+      if (this.eventEmitter && lodash__default["default"].isFinite(joinTimeoutMs) && joinTimeoutMs > 0) {
+        try {
+          this.eventEmitter.emit('voip.psstTimerArmed', {
+            sessionId: this.sessionId,
+            joinTimeoutMs,
+            bufferedChunks: bufferedAtArm,
+            armedAt
+          });
+        } catch (emitErr) {
+          // Never block the silence timer on listener errors.
+          debug$3(`voip.psstTimerArmed emission failed: ${emitErr && emitErr.message}`);
+        }
+      }
+      this.silenceTimeout = setTimeout(() => {
+        const fireDelay = Date.now() - armedAt;
+        if (this.botMsgs.length > 0) {
+          _info('psst_timer_fired', {
+            sessionId: this.sessionId,
+            bufferedChunks: this.botMsgs.length,
+            actualDelayMs: fireDelay,
+            scheduledDelayMs: joinTimeoutMs || 0,
+            outcome: 'emit'
+          });
+          debug$3('Silence Duration Timeout (JOIN/PSST):', joinTimeoutMs, 'ms');
+          sendBotMsg(joinBotMsg(this.botMsgs, this.joinLastPrevMsg));
+          this.firstMsg = false;
+          this.joinLastPrevMsg = this.botMsgs[this.botMsgs.length - 1];
+          this.botMsgs = [];
+          // Reset partial-driven extension budget for next cycle.
+          this.psstRearmCount = 0;
+          this.psstFirstRearmAt = null;
+        } else {
+          _info('psst_timer_fired', {
+            sessionId: this.sessionId,
+            bufferedChunks: 0,
+            actualDelayMs: fireDelay,
+            scheduledDelayMs: joinTimeoutMs || 0,
+            outcome: 'noop_empty_buffer'
+          });
+        }
+      }, joinTimeoutMs || 0);
+    };
+
+    // Flush buffered STT chunks on teardown so a late final is not lost when
+    // the PSST silence timer is cleared by Stop(). Falls back to the cached
+    // interim transcript (`lastPartialBotMsg`) when STT never delivered a
+    // final for the closing utterance. Must be called from every terminal
+    // path before `this.end` is flipped.
+    const flushPendingBotMsgs = reason => {
+      if (this.silenceTimeout) {
+        _info('psst_timer_cleared', {
+          sessionId: this.sessionId,
+          reason: `flush:${reason}`,
+          bufferedChunks: this.botMsgs && this.botMsgs.length || 0
+        });
+        clearTimeout(this.silenceTimeout);
+        this.silenceTimeout = null;
+      }
+      if (this.botMsgs && this.botMsgs.length > 0) {
+        const chunkCount = this.botMsgs.length;
+        _info('stt_buffer_flushed_on_end', {
+          sessionId: this.sessionId,
+          reason,
+          outcome: 'flushed',
+          chunks: chunkCount
+        });
+        debug$3(`Flushing ${chunkCount} buffered STT chunk(s) on ${reason}`);
+        sendBotMsg(joinBotMsg(this.botMsgs, this.joinLastPrevMsg));
+        this.firstMsg = false;
+        this.joinLastPrevMsg = this.botMsgs[this.botMsgs.length - 1];
+        this.botMsgs = [];
+        this.lastPartialBotMsg = null;
+        this.psstRearmCount = 0;
+        this.psstFirstRearmAt = null;
+        return;
+      }
+      if (this.lastPartialBotMsg && typeof this.lastPartialBotMsg.messageText === 'string' && this.lastPartialBotMsg.messageText.trim().length > 0) {
+        const recovered = this.lastPartialBotMsg;
+        const textLen = recovered.messageText.length;
+        const preview = recovered.messageText.trim().substring(0, 80);
+        _info('stt_partial_recovery_on_end', {
+          sessionId: this.sessionId,
+          reason,
+          outcome: 'partial_recovery',
+          messageLength: textLen,
+          message: preview
+        });
+        debug$3(`Recovering last STT partial on ${reason} (no final arrived): "${preview}"`);
+        sendBotMsg(recovered);
+        this.firstMsg = false;
+        this.joinLastPrevMsg = recovered;
+        this.lastPartialBotMsg = null;
+        return;
+      }
+      _info('stt_flush_noop', {
+        sessionId: this.sessionId,
+        reason,
+        outcome: 'noop',
+        sttPartialCount: this.sttPartialCount || 0
+      });
+      debug$3(`flushPendingBotMsgs(${reason}): nothing buffered, no partial available (sttPartialCount=${this.sttPartialCount || 0})`);
+    };
+    // Expose on the instance so Stop() (outside this closure) can call it as a final safety net.
+    this._flushPendingBotMsgs = flushPendingBotMsgs;
     const splitBotMsgs = botMsgs => {
       const splitSentences = s => s.match(new RegExp(`[^${this.caps[Capabilities.VOIP_STT_MESSAGE_HANDLING_PUNCTUATION]}]+[${this.caps[Capabilities.VOIP_STT_MESSAGE_HANDLING_PUNCTUATION]}]+`, 'g'));
       const botMsgsFinal = [];
@@ -236,21 +406,31 @@ class BotiumConnectorVoip {
     let httpInitRetries = 0;
     const connectHttp = async retryIndex => {
       retryIndex = retryIndex || 0;
+      let initCallUrl = '';
       try {
         const workerUrl = this.caps[Capabilities.VOIP_USE_GLOBAL_VOIP_WORKER] ? process.env.BOTIUM_VOIP_WORKER_URL : this.caps[Capabilities.VOIP_WORKER_URL].replace('wss', 'https').replace('ws', 'http');
         const baseUrl = workerUrl.endsWith('/') ? workerUrl.slice(0, -1) : workerUrl;
+        initCallUrl = `${baseUrl}/initCall`;
+        const postPayload = {
+          API_KEY: this.caps[Capabilities.VOIP_USE_GLOBAL_VOIP_WORKER] ? process.env.BOTIUM_VOIP_WORKER_APIKEY : this.caps[Capabilities.VOIP_WORKER_APIKEY]
+        };
+        const payloadForLog = {
+          ...postPayload,
+          API_KEY: postPayload.API_KEY != null && postPayload.API_KEY !== '' ? '[REDACTED]' : postPayload.API_KEY
+        };
+        debug$3(`HTTP initCall: POST ${initCallUrl} payload=${JSON.stringify(payloadForLog)}`);
         const res = await axios__default["default"]({
           method: 'post',
-          data: {
-            API_KEY: this.caps[Capabilities.VOIP_USE_GLOBAL_VOIP_WORKER] ? process.env.BOTIUM_VOIP_WORKER_APIKEY : this.caps[Capabilities.VOIP_WORKER_APIKEY]
-          },
-          url: `${baseUrl}/initCall`
+          data: postPayload,
+          url: initCallUrl
         });
         if (res) {
           data = res.data;
           headers = res.headers;
+          debug$3(`HTTP initCall: response status=${res.status} data=${this._getAxiosShortenedOutput(res.data)}`);
         }
       } catch (err) {
+        debug$3(`HTTP initCall: failed ${initCallUrl} — ${this._getAxiosErrOutput(err)}`);
         debug$3(`Retry ${retryIndex} / ${this.caps[Capabilities.VOIP_WEBSOCKET_CONNECT_MAXRETRIES]}: Connecting to VOIP Worker failed: ${err.message || 'Not reachable'}`);
         if (retryIndex === this.caps[Capabilities.VOIP_WEBSOCKET_CONNECT_MAXRETRIES]) {
           throw new Error(`Connecting to VOIP Worker failed: ${err.message || 'Not reachable'}`);
@@ -275,7 +455,15 @@ class BotiumConnectorVoip {
       const connectWs = retryIndex => {
         retryIndex = retryIndex || 0;
         return new Promise((resolve, reject) => {
-          if ('set-cookie' in headers) {
+          const useCookie = headers && 'set-cookie' in headers;
+          const connectPayload = useCookie ? {
+            withCookie: true,
+            cookieSize: headers['set-cookie'] && String(headers['set-cookie']).length || 0
+          } : {
+            withCookie: false
+          };
+          debug$3(`WebSocket connect: url=${wsEndpoint} attempt=${retryIndex + 1} max=${this.caps[Capabilities.VOIP_WEBSOCKET_CONNECT_MAXRETRIES] + 1} ` + `options=${JSON.stringify(connectPayload)}`);
+          if (useCookie) {
             this.ws = new ws__default["default"](wsEndpoint, {
               headers: {
                 Cookie: headers['set-cookie']
@@ -285,9 +473,11 @@ class BotiumConnectorVoip {
             this.ws = new ws__default["default"](wsEndpoint);
           }
           this.ws.on('open', () => {
+            debug$3(`WebSocket connect: result=open url=${wsEndpoint} attempt=${retryIndex + 1} ` + `readyState=${this.ws && this.ws.readyState}`);
             resolve(retryIndex);
           });
-          this.ws.on('error', () => {
+          this.ws.on('error', err => {
+            debug$3(`WebSocket connect: result=error url=${wsEndpoint} attempt=${retryIndex + 1} ` + `err=${err && err.message || err || 'unknown'}`);
             if (retryIndex === this.caps[Capabilities.VOIP_WEBSOCKET_CONNECT_MAXRETRIES]) {
               reject(new Error(`Websocket connection failed to ${wsEndpoint}`));
             }
@@ -320,9 +510,9 @@ class BotiumConnectorVoip {
               if (joinLogicHook && joinLogicHook.args && joinLogicHook.args.length > 0) {
                 silenceMs = parseInt(joinLogicHook.args[0], 10);
               }
-              // Fallback to global timeout if no per-step hook is set
+              // Fallback to effective timeout (subsequent if past first flush, else global)
               if (!lodash__default["default"].isFinite(silenceMs) || silenceMs <= 0) {
-                silenceMs = parseInt(this.caps[Capabilities.VOIP_STT_MESSAGE_HANDLING_TIMEOUT], 10);
+                silenceMs = parseInt(this._getEffectiveMessageHandlingTimeout(), 10);
               }
               // PSST: treat like JOIN, but subtract 500ms from timeout
               if (lodash__default["default"].isFinite(silenceMs) && silenceMs > 0) {
@@ -344,9 +534,15 @@ class BotiumConnectorVoip {
         this.silence = null;
         this.msgCount = 0;
         this.sttPartialCount = 0;
+        // Last interim transcript, used by `flushPendingBotMsgs` when no final arrives.
+        this.lastPartialBotMsg = null;
         this.firstMsg = true;
         this.firstSttInfoReceived = false;
         this.silenceTimeout = null;
+        // PSST re-arm tracking: new-utterance partials reset the silence timer,
+        // bounded by MAX_EXTENSION_MS to prevent infinite stranding.
+        this.psstRearmCount = 0;
+        this.psstFirstRearmAt = null;
         this.wsOpened = true;
         debug$3(`Websocket connection to ${wsEndpoint} opened.`);
         const sttHandling = this.caps[Capabilities.VOIP_STT_MESSAGE_HANDLING];
@@ -403,12 +599,45 @@ class BotiumConnectorVoip {
           }
         });
         this.ws.on('message', async data => {
-          const parsedData = JSON.parse(data);
-          // Allow fullRecord delivery even if Stop() was already called.
-          // Otherwise the recording can be dropped if the worker streams it late (common on hangup).
+          // Drop non-JSON gateway frames (rare, but crash the process without this guard).
+          let parsedData;
+          try {
+            parsedData = JSON.parse(data);
+            // Earliest local observation of the frame. Consumed downstream
+            // as the "bot finished speaking" anchor for `recordingEpochMs`
+            // (propagates via `sourceData = parsedData` reference).
+            parsedData._receivedAtMs = Date.now();
+          } catch (parseErr) {
+            const rawString = (() => {
+              try {
+                if (Buffer.isBuffer(data)) return data.toString('utf8');
+                if (typeof data === 'string') return data;
+                if (data && typeof data.toString === 'function') return data.toString();
+                return '<non-stringable>';
+              } catch (_) {
+                return '<unreadable>';
+              }
+            })();
+            const preview = rawString.length > 200 ? `${rawString.substring(0, 200)}...` : rawString;
+            debug$3(`${this.sessionId} - Ignoring non-JSON WS frame from gateway: ${preview}`);
+            if (typeof _info === 'function') {
+              try {
+                _info('ws_non_json_frame', {
+                  sessionId: this.sessionId,
+                  preview,
+                  byteLength: rawString.length,
+                  parseError: parseErr && parseErr.message ? parseErr.message : String(parseErr)
+                });
+              } catch (_infoErr) {/* structured logger is best-effort */}
+            }
+            return;
+          }
+          // After Stop(), still accept late-arriving recording frames
+          // (fullRecord*) and hard errors so `full_record.wav` is delivered
+          // on early-completion hangups. Post-Stop STT frames remain blocked.
           if (this.stopCalled) {
-            const allowedTypes = ['fullRecord', 'fullRecordStart', 'fullRecordChunk', 'fullRecordEnd', 'error'];
-            if (!parsedData || !parsedData.type || !allowedTypes.includes(parsedData.type)) {
+            const allowedPostStopTypes = ['fullRecord', 'fullRecordStart', 'fullRecordChunk', 'fullRecordEnd', 'error'];
+            if (!parsedData || !allowedPostStopTypes.includes(parsedData.type)) {
               debug$3(`${this.sessionId} - Stop already called, ignoring incoming message`);
               return;
             }
@@ -517,6 +746,7 @@ class BotiumConnectorVoip {
               connectDurationSec: parsedData.connectDuration || null,
               sttPartialCount: this.sttPartialCount
             });
+            flushPendingBotMsgs('callinfo_disconnected');
             const apiKey = this._extractApiKey(this._getBody(Capabilities.VOIP_STT_BODY));
             if (parsedData.connectDuration && parsedData.connectDuration > 0) {
               this.eventEmitter.emit('CONSUMPTION_METADATA', this, {
@@ -529,6 +759,7 @@ class BotiumConnectorVoip {
             }
           }
           if (parsedData && parsedData.type === 'error') {
+            flushPendingBotMsgs('error');
             this.end = true;
             reject(new Error(`Error: ${parsedData.message}`));
             sendBotMsg(new Error(`Error: ${parsedData.message}`));
@@ -553,11 +784,15 @@ class BotiumConnectorVoip {
               source: 'fullRecordEnd',
               base64Len
             });
+            // Flush before `this.end = true` so the buffered final STT is not
+            // dropped when Stop() clears the PSST silence timer on teardown.
+            flushPendingBotMsgs('fullRecordEnd');
             this.end = true;
           }
           if (parsedData && parsedData.type === 'silence') {
             if (lodash__default["default"].isNil(this._getIgnoreSilenceDurationAsserterLogicHook(this.convoStep))) {
               if (lodash__default["default"].isNil(this._getJoinLogicHook(this.convoStep)) && parsedData.data.silence.length > 0) {
+                flushPendingBotMsgs('silence_exceeded');
                 this.end = true;
                 sendBotMsg(new Error(`Silence Duration of ${parsedData.data.silence[0][2].toFixed(2)}s exceeded General Silence Duration Timeout of ${this.caps[Capabilities.VOIP_SILENCE_DURATION_TIMEOUT] / 1000}s`));
               }
@@ -572,12 +807,69 @@ class BotiumConnectorVoip {
               source: 'fullRecord',
               base64Len: (base64 || '').length
             });
+            flushPendingBotMsgs('fullRecord');
             this.end = true;
           }
           if (parsedData && parsedData.data && parsedData.data.final === false) {
             this.sttPartialCount++;
+            const partialText = parsedData.data.message;
+            if (typeof partialText === 'string' && partialText.trim().length > 0) {
+              this.lastPartialBotMsg = {
+                messageText: partialText,
+                sourceData: Object.assign({}, parsedData, {
+                  partialRecovery: true
+                })
+              };
+            }
+            const partialPreview = typeof partialText === 'string' ? partialText.trim().substring(0, 60) : '';
+            _info('stt_partial_received', {
+              sessionId: this.sessionId,
+              partialIndex: this.sttPartialCount,
+              preview: partialPreview,
+              bufferedChunks: this.botMsgs && this.botMsgs.length || 0,
+              timerActive: !!this.silenceTimeout
+            });
+            // Emit liveness keep-alive so waiters can distinguish "bot silent"
+            // from "bot streaming partials between finals".
+            if (this.caps[Capabilities.VOIP_EMIT_SPECULATIVE_TEXT] && this.eventEmitter && typeof partialText === 'string' && partialText.trim().length > 0) {
+              this.eventEmitter.emit('voip.botActivity', {
+                sessionId: this.sessionId,
+                kind: 'partial',
+                partialIndex: this.sttPartialCount,
+                bufferedChunks: this.botMsgs && this.botMsgs.length || 0
+              });
+            }
+            // PSST partial timer logic:
+            //   Empty buffer → clear timer (final will arm fresh).
+            //   Buffered finals + new-utterance partial → re-arm within cap.
+            //   Tail/echo or cap-exceeded partials → ignore (legacy path).
             if (this.silenceTimeout) {
-              clearTimeout(this.silenceTimeout);
+              if (!this.botMsgs || this.botMsgs.length === 0) {
+                clearTimeout(this.silenceTimeout);
+                this.silenceTimeout = null;
+              } else {
+                const sttHandling = this.caps[Capabilities.VOIP_STT_MESSAGE_HANDLING];
+                const isPsstMode = sttHandling === 'PSST';
+                if (isPsstMode && typeof partialText === 'string' && partialText.trim().length > 0) {
+                  const MAX_EXTENSION_MS = 60000;
+                  const now = Date.now();
+                  const withinCap = this.psstFirstRearmAt == null || now - this.psstFirstRearmAt < MAX_EXTENSION_MS;
+                  if (withinCap && partialLooksLikeNewUtterance(partialText, this.botMsgs)) {
+                    if (this.psstFirstRearmAt == null) this.psstFirstRearmAt = now;
+                    this.psstRearmCount++;
+                    _info('psst_timer_extended', {
+                      sessionId: this.sessionId,
+                      rearmCount: this.psstRearmCount,
+                      msSinceFirstRearm: now - this.psstFirstRearmAt,
+                      bufferedChunks: this.botMsgs.length,
+                      reason: 'new_utterance_partial',
+                      partialPreview
+                    });
+                    // armJoinSilenceTimer() handles clearing the existing timeout.
+                    armJoinSilenceTimer();
+                  }
+                }
+              }
             }
             if (lodash__default["default"].isNil(this._getIgnoreSilenceDurationAsserterLogicHook(this.convoStep))) {
               if (!this.firstSttInfoReceived && lodash__default["default"].isNil(this._getJoinLogicHook(this.convoStep)) && this.caps[Capabilities.VOIP_SILENCE_DURATION_TIMEOUT_START_ENABLE] && parsedData.data.start && parsedData.data.start * 1000 > this.caps[Capabilities.VOIP_SILENCE_DURATION_TIMEOUT_START]) {
@@ -605,7 +897,7 @@ class BotiumConnectorVoip {
                     matched = true;
                   }
                 } else if (lodash__default["default"].isNil(joinLogicHook) && isJoinMethod) {
-                  const joinTimeoutMs = toJoinTimeoutMs(this.caps[Capabilities.VOIP_STT_MESSAGE_HANDLING_TIMEOUT]);
+                  const joinTimeoutMs = toJoinTimeoutMs(this._getEffectiveMessageHandlingTimeout());
                   if (lodash__default["default"].isFinite(joinTimeoutMs) && joinTimeoutMs > 0 && silenceDuration > joinTimeoutMs / 1000) {
                     matched = true;
                   }
@@ -625,6 +917,8 @@ class BotiumConnectorVoip {
             const msgText = parsedData.data.message || '';
             const msgLen = typeof msgText === 'string' ? msgText.length : 0;
             const msgPreview = typeof msgText === 'string' ? msgText.trim().substring(0, 80) : '';
+            // A final supersedes the cached interim; clear to avoid duplicate tail emission.
+            this.lastPartialBotMsg = null;
             debug$3(`Message: ${parsedData.data.message} / Confidence Score: ${this._getConfidenceScore(parsedData)} (Threshold: ${confidenceThreshold})`);
             _info('stt_final', {
               sessionId: this.sessionId,
@@ -702,27 +996,30 @@ class BotiumConnectorVoip {
               this.prevData = parsedData;
               if (successfulConfidenceScore) {
                 this.botMsgs.push(botMsg);
-                const sttHandling = this.caps[Capabilities.VOIP_STT_MESSAGE_HANDLING];
-                const isPsst = sttHandling === 'PSST';
-                const toJoinTimeoutMs = ms => {
-                  const parsed = parseInt(ms, 10);
-                  if (!lodash__default["default"].isFinite(parsed) || parsed <= 0) return null;
-                  return isPsst ? Math.max(0, parsed - 500) : parsed;
-                };
-                const joinLogicHook = this._getJoinLogicHook(this.convoStep);
-                let joinTimeoutMs = toJoinTimeoutMs(lodash__default["default"].get(joinLogicHook, 'args[0]'));
-                if (!lodash__default["default"].isFinite(joinTimeoutMs) || joinTimeoutMs <= 0) {
-                  joinTimeoutMs = toJoinTimeoutMs(this.caps[Capabilities.VOIP_STT_MESSAGE_HANDLING_TIMEOUT]);
+                if (this.caps[Capabilities.VOIP_EMIT_SPECULATIVE_TEXT] && this.eventEmitter) {
+                  const tentative = joinBotMsg(this.botMsgs, this.joinLastPrevMsg);
+                  this._speculativeTurnToken++;
+                  // speech{Start,End}Sec are audio-clock offsets (seconds since
+                  // call connect) taken from the STT worker, so downstream
+                  // consumers can align with the recording playhead directly.
+                  const firstChunkStart = lodash__default["default"].get(this.botMsgs, '[0].sourceData.data.start', null);
+                  const thisFrameStart = lodash__default["default"].get(parsedData, 'data.start', null);
+                  const thisFrameEnd = lodash__default["default"].get(parsedData, 'data.end', null);
+                  const speechStartSec = lodash__default["default"].isFinite(firstChunkStart) ? firstChunkStart : lodash__default["default"].isFinite(thisFrameStart) ? thisFrameStart : null;
+                  const speechEndSec = lodash__default["default"].isFinite(thisFrameEnd) ? thisFrameEnd : null;
+                  this.eventEmitter.emit('voip.speculativeBotText', {
+                    sessionId: this.sessionId,
+                    messageText: tentative.messageText,
+                    turnToken: this._speculativeTurnToken,
+                    speechStartSec,
+                    speechEndSec
+                  });
                 }
-                this.silenceTimeout = setTimeout(() => {
-                  if (this.botMsgs.length > 0) {
-                    debug$3('Silence Duration Timeout (JOIN/PSST):', joinTimeoutMs, 'ms');
-                    sendBotMsg(joinBotMsg(this.botMsgs, this.joinLastPrevMsg));
-                    this.firstMsg = false;
-                    this.joinLastPrevMsg = this.botMsgs[this.botMsgs.length - 1];
-                    this.botMsgs = [];
-                  }
-                }, joinTimeoutMs || 0);
+
+                // New final arrived — reset extension budget for next pause.
+                this.psstRearmCount = 0;
+                this.psstFirstRearmAt = null;
+                armJoinSilenceTimer();
               }
             }
           }
@@ -775,6 +1072,22 @@ class BotiumConnectorVoip {
         const preferVoice = !!preferVoiceCapRaw;
         const skipTtsForMixedInput = preferVoice && hasText && hasVoiceMedia;
         debug$3(`UserSays routing: hasText=${hasText} hasVoiceMedia=${hasVoiceMedia} preferVoice=${preferVoice} preferVoiceRaw=${JSON.stringify(preferVoiceCapRaw)} skipTtsForMixedInput=${skipTtsForMixedInput}`);
+
+        // Stamp `msg.voipAgent` at the moment bytes leave the WebSocket so
+        // the coach can place the agent turn on the recording timeline.
+        // `requestedDurationMs` is the best estimate of on-wire playback
+        // length (DTMF tones × digits, TTS synth output, parsed media duration).
+        const stampAgentWire = (wireKind, requestedDurationMs, extras = {}) => {
+          msg.voipAgent = {
+            wireSentAtMs: Date.now(),
+            inputType,
+            wireKind,
+            requestedDurationMs: Math.max(0, Math.round(requestedDurationMs || 0)),
+            ...extras
+          };
+        };
+        // Twilio default: 100 ms tone + 100 ms gap per digit. Drives agent-bar width only.
+        const DTMF_MS_PER_DIGIT = 200;
         if (msg && msg.buttons && msg.buttons.length > 0) {
           const digits = sanitizeDtmfDigits(msg.buttons[0].payload);
           if (!digits) {
@@ -787,6 +1100,9 @@ class BotiumConnectorVoip {
             digits,
             sessionId: this.sessionId
           });
+          stampAgentWire('dtmf', digits.length * DTMF_MS_PER_DIGIT, {
+            digitCount: digits.length
+          });
           this.ws.send(request);
         } else if (msg && msg.messageText) {
           // Check for DTMF tag in messageText: <DTMF>1234</DTMF>
@@ -808,6 +1124,9 @@ class BotiumConnectorVoip {
               digits,
               sessionId: this.sessionId
             });
+            stampAgentWire('dtmf', digits.length * DTMF_MS_PER_DIGIT, {
+              digitCount: digits.length
+            });
             this.ws.send(request);
             return resolve();
           }
@@ -822,8 +1141,11 @@ class BotiumConnectorVoip {
               if (!ttsRequest) return reject(new Error('TTS not configured, only audio input supported'));
               msg.sourceData = ttsRequest;
               let ttsResult = null;
+              const ttsStartedAt = Date.now();
+              let ttsSynthMs = 0;
               try {
                 ttsResult = await this._getTtsAudio(ttsRequest, msg.messageText);
+                ttsSynthMs = Date.now() - ttsStartedAt;
               } catch (err) {
                 return reject(new Error(`TTS "${msg.messageText}" failed - ${this._getAxiosErrOutput(err)}`));
               }
@@ -855,6 +1177,10 @@ class BotiumConnectorVoip {
                   mimeType: 'audio/wav',
                   base64: b64Buffer
                 });
+                stampAgentWire('tts', (duration || 0) * 1000, {
+                  ttsSynthMs,
+                  textLength: msg.messageText ? msg.messageText.length : 0
+                });
                 this.ws.send(request);
               } else {
                 return reject(new Error('TTS failed, response is empty'));
@@ -876,6 +1202,10 @@ class BotiumConnectorVoip {
             const botText = this._lastBotSaysText ? this._lastBotSaysText.substring(0, 120) : '<unknown>';
             debug$3(`Latency (bot says -> sendAudio/MEDIA): ${latencyMs} ms (last bot: ${botText})`);
           }
+          // Stamp now; `requestedDurationMs` is backfilled once media metadata is parsed.
+          stampAgentWire('media', 0, {
+            mediaUri: msg.media[0].mediaUri || null
+          });
           this.ws.send(request);
           msg.attachments.push({
             name: msg.media[0].mediaUri,
@@ -887,6 +1217,9 @@ class BotiumConnectorVoip {
             if (metadata && metadata.format && metadata.format.duration) {
               debug$3('Audio duration of user audio:', metadata.format.duration, 'seconds');
               duration = Math.round(metadata.format.duration);
+              if (msg.voipAgent) {
+                msg.voipAgent.requestedDurationMs = Math.max(0, Math.round((duration || 0) * 1000));
+              }
             } else {
               reject(new Error('Could not determine audio duration from metadata'));
             }
@@ -894,7 +1227,11 @@ class BotiumConnectorVoip {
             reject(new Error(`Getting audio duration failed: ${err.message}`));
           }
         }
-        setTimeout(resolve, duration * 1000);
+        const requestedDurationMs = Math.max(0, Math.round((duration || 0) * 1000));
+        if (requestedDurationMs <= 0) {
+          return resolve();
+        }
+        setTimeout(resolve, requestedDurationMs);
       }, 0);
     });
   }
@@ -1100,6 +1437,16 @@ class BotiumConnectorVoip {
   _extractApiKey(body) {
     return lodash__default["default"].get(body, 'polly.credentials.accessKeyId') || lodash__default["default"].get(body, 'google.credentials.client_email') || lodash__default["default"].get(body, 'ibm.credentials.apikey') || lodash__default["default"].get(body, 'awstranscribe.credentials.accessKeyId') || lodash__default["default"].get(body, 'azure.credentials.subscriptionKey') || null;
   }
+
+  // After the first flush, use the shorter SUBSEQUENT timeout if configured.
+  // Falls back to the global timeout — fully backward-compatible.
+  _getEffectiveMessageHandlingTimeout() {
+    if (!this.firstMsg) {
+      const sub = parseInt(this.caps[Capabilities.VOIP_STT_MESSAGE_HANDLING_TIMEOUT_SUBSEQUENT], 10);
+      if (lodash__default["default"].isFinite(sub) && sub > 0) return sub;
+    }
+    return this.caps[Capabilities.VOIP_STT_MESSAGE_HANDLING_TIMEOUT];
+  }
   _getJoinLogicHook(convoStep) {
     if (lodash__default["default"].isNil(convoStep)) return null;
     if (lodash__default["default"].isNil(convoStep.logicHooks)) return null;