fix: harden realtime pipeline lifecycle

backend/services/pipecat/pipeline.py

@@ -103,7 +103,7 @@ from services.realtime.protocol import (
     PipelineProtocolRuntime,
     RealtimeProviderControlFrame,
 )
-from pipecat.workers.runner import WorkerRunner
+from services.pipecat.pipeline_runner import run_media_worker
 
 
 KNOWLEDGE_TOOL_NAME = "search_knowledge_base"
@@ -260,6 +260,7 @@ async def run_pipeline(
             assistant_id=assistant_id,
             channel=channel,
             protocol_adapter=protocol_adapter,
+            client_tool_names=client_tool_names,
         )
         return
 
@@ -987,25 +988,7 @@ async def run_pipeline(
         submit_user_input=submit_user_input,
         client_tools=client_tools,
     )
-    runner = WorkerRunner(handle_sigint=False)
-    run_status = "completed"
-    can_finalize_recorder = True
-    try:
-        await runner.add_workers(worker)
-        await runner.run()
-    except GeneratorExit:
-        # A coroutine being synchronously closed cannot perform async cleanup.
-        # The WebRTC route now prevents this by retaining every pipeline task;
-        # keep this guard so a future unmanaged caller cannot corrupt asyncpg.
-        run_status = "failed"
-        can_finalize_recorder = False
-        raise
-    except Exception:
-        run_status = "failed"
-        raise
-    finally:
-        if recorder and can_finalize_recorder:
-            await recorder.finish(status=run_status)
+    await run_media_worker(worker, recorder)
     logger.info("管线已结束")
 
 
@@ -1018,6 +1001,7 @@ async def run_realtime_pipeline(
     assistant_id: str | None = None,
     channel: str = "webrtc",
     protocol_adapter: PipelineProtocolAdapter | None = None,
+    client_tool_names: set[str] | None = None,
 ) -> None:
     """Run a speech-to-speech model that owns ASR, reasoning, and synthesis."""
     realtime = create_realtime_service(
@@ -1239,20 +1223,5 @@ async def run_realtime_pipeline(
         vision_enabled=vision_enabled,
         vision_state=vision_state,
     )
-    runner = WorkerRunner(handle_sigint=False)
-    run_status = "completed"
-    can_finalize_recorder = True
-    try:
-        await runner.add_workers(worker)
-        await runner.run()
-    except GeneratorExit:
-        run_status = "failed"
-        can_finalize_recorder = False
-        raise
-    except Exception:
-        run_status = "failed"
-        raise
-    finally:
-        if recorder and can_finalize_recorder:
-            await recorder.finish(status=run_status)
+    await run_media_worker(worker, recorder)
     logger.info("Realtime 管线已结束")

backend/services/pipecat/pipeline_runner.py

@@ -0,0 +1,56 @@
+"""Run a media worker and persist its actual terminal outcome."""
+
+import asyncio
+
+from pipecat.frames.frames import CancelFrame, EndFrame, ErrorFrame
+from pipecat.pipeline.worker import PipelineWorker
+from pipecat.workers.runner import WorkerRunner
+
+from services.conversation_history import ConversationRecorder
+
+
+async def run_media_worker(
+    worker: PipelineWorker,
+    recorder: ConversationRecorder | None,
+) -> None:
+    # A runner can return normally after a fatal ErrorFrame or a failed worker.
+    # Only an observed, expected terminal frame counts as normal completion.
+    status = "failed"
+    fatal_error = False
+
+    @worker.event_handler("on_pipeline_error")
+    async def on_pipeline_error(_worker, frame: ErrorFrame):
+        nonlocal status, fatal_error
+        if frame.fatal:
+            fatal_error = True
+            status = "failed"
+
+    @worker.event_handler("on_pipeline_finished")
+    async def on_pipeline_finished(_worker, frame):
+        nonlocal status
+        normal_end = isinstance(frame, EndFrame) or (
+            isinstance(frame, CancelFrame)
+            and frame.reason in {"client_disconnected", "idle timeout"}
+        )
+        if normal_end and not fatal_error:
+            status = "completed"
+
+    runner = WorkerRunner(handle_sigint=False)
+    can_finalize = True
+    try:
+        await runner.add_workers(worker)
+        await runner.run()
+        # Pipecat's runner consumes cancellation while draining its workers.
+        # Preserve the owning server task's cancellation after that cleanup.
+        owner = asyncio.current_task()
+        if owner is not None and owner.cancelling():
+            raise asyncio.CancelledError
+    except GeneratorExit:
+        can_finalize = False  # Synchronously closed coroutines cannot await.
+        raise
+    except BaseException:
+        status = "failed"
+        raise
+    finally:
+        if recorder and can_finalize:
+            await recorder.finish(status=status)

backend/services/pipecat/processors.py

@@ -657,7 +657,7 @@ class ConversationHistoryProcessor(FrameProcessor):
         await super().process_frame(frame, direction)
         await self.push_frame(frame, direction)
         if self._recorder and isinstance(frame, OutputTransportMessageUrgentFrame):
-            await self._recorder.record_transport_message(frame.message)
+            self._recorder.record_transport_message_later(frame.message)
 
 
 class KnowledgeRetrievalProcessor(FrameProcessor):