fix(workflow): track fixed speech at transport output

backend/services/pipecat/call_lifecycle.py

@@ -3,14 +3,66 @@
 from __future__ import annotations
 
 import asyncio
-from collections import deque
 from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
 
 from loguru import logger
-from pipecat.frames.frames import BotStartedSpeakingFrame, BotStoppedSpeakingFrame
+from pipecat.frames.frames import (
+    BotStartedSpeakingFrame,
+    BotStoppedSpeakingFrame,
+    DataFrame,
+    InterruptionFrame,
+)
 from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 
 
+class SpeechPlaybackCompletion:
+    """Awaitable completed by its exact marker at the transport output."""
+
+    def __init__(self, coordinator: CallEndCoordinator):
+        self._coordinator = coordinator
+        self._future: asyncio.Future[None] = (
+            asyncio.get_running_loop().create_future()
+        )
+        self._queued = False
+
+    def __await__(self):
+        return self._future.__await__()
+
+    def done(self) -> bool:
+        return self._future.done()
+
+    @property
+    def queued(self) -> bool:
+        return self._queued
+
+    def mark_queued(self) -> None:
+        self._queued = True
+
+    async def mark_played(self) -> None:
+        await self._coordinator.complete_tracked_speech(self)
+
+    def _resolve(self) -> None:
+        if not self._future.done():
+            self._future.set_result(None)
+
+
+@dataclass
+class FixedSpeechPlaybackMarkerFrame(DataFrame):
+    """Ordered frame that identifies one fixed utterance at transport output."""
+
+    completion: SpeechPlaybackCompletion
+
+
+def playback_marker_for(
+    completion: Awaitable[None] | None,
+) -> FixedSpeechPlaybackMarkerFrame | None:
+    """Build a marker only for the production call-end coordinator."""
+    if not isinstance(completion, SpeechPlaybackCompletion):
+        return None
+    return FixedSpeechPlaybackMarkerFrame(completion=completion)
+
+
 class CallEndCoordinator:
     """End immediately or after the currently armed closing speech finishes."""
 
@@ -22,17 +74,10 @@ class CallEndCoordinator:
         self._speech_stopped = asyncio.Event()
         self._speech_stopped.set()
         self._response_speech_started = False
-        self._tracked_speeches = 0
-        self._tracked_speech_completions: deque[asyncio.Future[None]] = deque()
+        self._tracked_speech_completions: set[SpeechPlaybackCompletion] = set()
         self._finish_after_tracked_speech = False
         self._finished = False
         self._reason = "completed"
-        # Only BotStoppedSpeakingFrame that follows a tracked BotStartedSpeakingFrame
-        # decrements the tracked-speech counter.  This prevents a stale or cross-talk
-        # stop frame (e.g. from a preceding LLM utterance) from consuming the counter
-        # meant for a fixed end-node message.
-        self._pending_tracked_starts = 0
-        self._current_speech_is_tracked = False
 
     @property
     def ending(self) -> bool:
@@ -59,18 +104,32 @@ class CallEndCoordinator:
         """Wait for the next observed bot speech to finish."""
         self._armed = True
 
-    def track_speech(self) -> Awaitable[None]:
+    def track_speech(self) -> SpeechPlaybackCompletion:
         """Register fixed speech and return its transport completion signal."""
-        completion = asyncio.get_running_loop().create_future()
-        self._tracked_speech_completions.append(completion)
-        self._tracked_speeches += 1
-        self._pending_tracked_starts += 1
+        completion = SpeechPlaybackCompletion(self)
+        self._tracked_speech_completions.add(completion)
         return completion
 
+    async def complete_tracked_speech(
+        self,
+        completion: SpeechPlaybackCompletion,
+    ) -> None:
+        """Complete one fixed utterance when its marker reaches output."""
+        if completion not in self._tracked_speech_completions:
+            return
+        self._tracked_speech_completions.remove(completion)
+        completion._resolve()
+        if (
+            self._finish_after_tracked_speech
+            and not self._tracked_speech_completions
+        ):
+            logger.info("所有工作流结束语播报完毕,挂断通话")
+            await self.finish()
+
     async def arm_after_tracked_speech(self) -> None:
         """Finish after every already queued fixed utterance has played."""
         self._finish_after_tracked_speech = True
-        if self._tracked_speeches == 0:
+        if not self._tracked_speech_completions:
             await self.finish()
 
     async def finish_after_current_speech(self, *, has_text: bool) -> None:
@@ -90,30 +149,25 @@ class CallEndCoordinator:
         await self._queue_end(self._reason)
 
     async def observe(self, frame) -> None:
-        if isinstance(frame, BotStartedSpeakingFrame):
+        if isinstance(frame, InterruptionFrame):
+            # Pipecat discards queued data frames on interruption, including
+            # playback markers. Treat already queued fixed speech as stopped so
+            # an interrupted Message cannot block a later EndNode forever.
+            interrupted = tuple(
+                completion
+                for completion in self._tracked_speech_completions
+                if completion.queued
+            )
+            for completion in interrupted:
+                await self.complete_tracked_speech(completion)
+        elif isinstance(frame, BotStartedSpeakingFrame):
             self._speaking = True
             self._speech_stopped.clear()
             self._response_speech_started = True
-            if self._pending_tracked_starts > 0:
-                self._pending_tracked_starts -= 1
-                self._current_speech_is_tracked = True
         elif isinstance(frame, BotStoppedSpeakingFrame) and self._speaking:
             self._speaking = False
             self._speech_stopped.set()
-            if self._current_speech_is_tracked:
-                self._current_speech_is_tracked = False
-                if self._tracked_speeches > 0:
-                    self._tracked_speeches -= 1
-                    completion = self._tracked_speech_completions.popleft()
-                    if not completion.done():
-                        completion.set_result(None)
-            if (
-                self._finish_after_tracked_speech
-                and self._tracked_speeches == 0
-            ):
-                logger.info("所有工作流结束语播报完毕,挂断通话")
-                await self.finish()
-            elif self._armed:
+            if self._armed:
                 logger.info("结束语播报完毕,挂断通话")
                 await self.finish()