Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
fix(app): allow WebRTC sessions to close during startup (#3190)
Zheng Haoran5d07cfc1270b
diff --git a/src/agentscope/app/_service/_webrtc_session.py b/src/agentscope/app/_service/_webrtc_session.pyindex 612baa3be..53a8b0442 100644--- a/src/agentscope/app/_service/_webrtc_session.py+++ b/src/agentscope/app/_service/_webrtc_session.py@@ -56,6 +56,9 @@ class WebRTCSession:self._close_task: asyncio.Task[None] | None = Noneself._close_lock = asyncio.Lock()self._closing = False+ self._closed = False+ self._startup_complete = False+ self._finalizing = Falseself._lock_acquired = asyncio.Event()self._persisted_messages: dict[str, str] = {}self._open_user_replies: set[str] = set()@@ -65,8 +68,12 @@ class WebRTCSession:def start(self) -> None:"""Start the agent pump after WebRTC negotiation succeeds."""- if self._task is not None:- raise RuntimeError("The WebRTC session is already running.")+ if (+ self._task is not None+ or self._closing+ or self._close_task is not None+ ):+ raise RuntimeError("The WebRTC session is running or closed.")self._task = asyncio.create_task(self._run(),name=f"webrtc-session-{self.session_id}",@@ -74,10 +81,10 @@ class WebRTCSession:def request_close(self) -> None:"""Schedule one owned close task from a synchronous callback."""- if self._closing or self._close_task is not None:+ if self._close_task is not None:returnself._close_task = asyncio.create_task(- self.close(),+ self._close(),name=f"webrtc-session-close-{self.session_id}",)self._close_task.add_done_callback(self._on_close_done)@@ -96,18 +103,39 @@ class WebRTCSession:async def close(self) -> None:"""End the transport and wait for persistence to finish."""+ self.request_close()+ assert self._close_task is not None+ await asyncio.shield(self._close_task)++ async def _close(self) -> None:+ """Own shutdown independently of cancellation of close callers."""+ task = self._taskasync with self._close_lock:if not self._closing:self._closing = Trueawait self.transport.close()+ if (+ task is not None+ and task is not asyncio.current_task()+ and not self._startup_complete+ and not self._finalizing+ ):+ task.cancel()- task = self._taskif task is not None and task is not asyncio.current_task():- if not self._lock_acquired.is_set():- task.cancel()- await asyncio.gather(task, return_exceptions=True)- elif task is None:+ await asyncio.gather(asyncio.shield(task), return_exceptions=True)+ # A task cancelled before its first step never enters _run's finally.+ await self._close_resources()++ async def _close_resources(self) -> None:+ """Close the peer and retire this session exactly once."""+ async with self._close_lock:+ if self._closed:+ return+ self._closing = True+ await self.transport.close()await self.peer_connection.close()+ self._closed = Trueself._on_closed(self)async def wait_until_lock_acquired(self, timeout: float) -> bool:@@ -123,6 +151,8 @@ class WebRTCSession:async def _run(self) -> None:"""Hold the session lock while forwarding events to the SSE log."""+ if self._close_task is not None:+ returntry:async with self.message_bus.acquire_lock(MessageBusKeys.session_lock(self.session_id),@@ -137,6 +167,7 @@ class WebRTCSession:}async with self.transport:async with self.agent:+ self._startup_complete = Trueasync for event in self.agent.reply_stream(self.transport,):@@ -195,6 +226,7 @@ class WebRTCSession:exc,)finally:+ self._finalizing = Truetry:async with self.message_bus.acquire_lock(MessageBusKeys.session_event_checkpoint_lock(@@ -233,9 +265,13 @@ class WebRTCSession:)async with self._close_lock:self._closing = True- await self.transport.close()- await self.peer_connection.close()- self._on_closed(self)+ try:+ if self.agent is not None and not self._startup_complete:+ # __aexit__ is not called when provider setup is cancelled+ # during the agent's __aenter__.+ await self.agent.close()+ finally:+ await self._close_resources()async def _checkpoint_state(self,diff --git a/tests/webrtc_audio_transport_test.py b/tests/webrtc_audio_transport_test.pyindex b83a74a54..de57699da 100644--- a/tests/webrtc_audio_transport_test.py+++ b/tests/webrtc_audio_transport_test.py@@ -20,6 +20,7 @@ from av import AudioFrame as AVAudioFramefrom fastapi import HTTPExceptionfrom agentscope.agent import RealtimeAgent+from agentscope.credential import GeminiCredentialfrom agentscope.app._router._realtime import _create_realtime_offerfrom agentscope.app._router._schema import (RealtimeOfferRequest,@@ -49,7 +50,9 @@ from agentscope.message import ToolCallBlock, ToolResultState, UserMsgfrom agentscope.realtime import (AudioFrame,DashScopeAudioRealtimeModel,+ GeminiRealtimeModel,RealtimeModelBase,+ RealtimeModelCard,)from agentscope.realtime import _events as mefrom agentscope.tool import FunctionTool, Toolkit@@ -165,6 +168,34 @@ class _FakeAgent:return None+class _UnacknowledgedSetupSocket:+ """Keep a real Gemini connect waiting for its setup acknowledgement."""++ def __init__(self) -> None:+ self.setup_sent = asyncio.Event()+ self.closed = False+ self._incoming: asyncio.Queue[str | None] = asyncio.Queue()++ async def send(self, frame: str) -> None:+ """Record that the model sent its setup frame."""+ del frame+ self.setup_sent.set()++ def __aiter__(self) -> "_UnacknowledgedSetupSocket":+ return self++ async def __anext__(self) -> str:+ frame = await self._incoming.get()+ if frame is None:+ raise StopAsyncIteration+ return frame++ async def close(self) -> None:+ """Close the socket and release the provider's reader."""+ self.closed = True+ self._incoming.put_nowait(None)++class _FakeTransport:"""Idempotently closing transport double."""@@ -1625,6 +1656,383 @@ class WebRTCSessionTest(unittest.IsolatedAsyncioTestCase):},)+ async def test_closed_session_rejects_a_late_start(self) -> None:+ """A retired session must not launch another provider connection."""+ create_agent = AsyncMock()+ session = _make_session(+ agent_factory=create_agent,+ storage=_FakeStorage(),+ message_bus=_FakeMessageBus(),+ on_closed=lambda _: None,+ )+ await session.close()+ try:+ with self.assertRaises(RuntimeError):+ session.start()+ create_agent.assert_not_awaited()+ finally:+ if session._task is not None:+ session._task.cancel()+ await asyncio.gather(session._task, return_exceptions=True)++ async def test_close_before_runner_starts_is_idempotent(self) -> None:+ """Cancellation before the task's first step still owns cleanup."""+ transport = _FakeTransport()+ peer_connection = _FakePeerConnection()+ create_agent = AsyncMock()+ closed_sessions: list[WebRTCSession] = []+ session = _make_session(+ transport=transport,+ peer_connection=peer_connection,+ agent_factory=create_agent,+ storage=_FakeStorage(),+ message_bus=_FakeMessageBus(),+ on_closed=closed_sessions.append,+ )+ session.start()+ await session.close()+ await session.close()+ create_agent.assert_not_awaited()+ self.assertTrue(transport.closed)+ self.assertTrue(peer_connection.closed)+ self.assertEqual(closed_sessions, [session])++ async def test_close_cancels_agent_assembly_after_lock_acquisition(+ self,+ ) -> None:+ """Owning the run lock does not make unfinished startup drainable."""+ entered = asyncio.Event()+ cancelled = asyncio.Event()+ transport = _FakeTransport()+ peer_connection = _FakePeerConnection()+ message_bus = _FakeMessageBus()+ storage = _FakeStorage()+ closed_sessions: list[WebRTCSession] = []++ async def _create_agent() -> _FakeAgent:+ entered.set()+ try:+ await asyncio.Event().wait()+ finally:+ cancelled.set()+ raise AssertionError("The blocked factory must be cancelled.")++ session = _make_session(+ transport=transport,+ peer_connection=peer_connection,+ agent_factory=_create_agent,+ storage=storage,+ message_bus=message_bus,+ on_closed=closed_sessions.append,+ )+ session.start()+ close_task: asyncio.Task[None] | None = None+ try:+ await asyncio.wait_for(entered.wait(), timeout=1)+ self.assertTrue(await session.wait_until_lock_acquired(1))+ close_task = asyncio.create_task(session.close())+ await asyncio.wait_for(asyncio.shield(close_task), timeout=1)+ self.assertTrue(cancelled.is_set())+ self.assertTrue(transport.closed)+ self.assertTrue(peer_connection.closed)+ self.assertFalse(message_bus.held_locks)+ self.assertEqual(storage.calls, [])+ self.assertEqual(closed_sessions, [session])+ finally:+ if session._task is not None:+ session._task.cancel()+ await asyncio.gather(session._task, return_exceptions=True)+ if close_task is not None:+ await asyncio.gather(close_task, return_exceptions=True)++ async def test_close_cancels_provider_setup_and_closes_its_socket(+ self,+ ) -> None:+ """A cancelled agent __aenter__ must still release its model reader."""+ socket = _UnacknowledgedSetupSocket()+ model = GeminiRealtimeModel(+ "test-gemini",+ credential=GeminiCredential(api_key="test-key"),+ model_card=RealtimeModelCard(+ name="test-gemini",+ label="test",+ input_sample_rate=16_000,+ output_sample_rate=24_000,+ ),+ )+ agent = RealtimeAgent(name="test", system_prompt="", model=model)+ transport = _FakeTransport()+ peer_connection = _FakePeerConnection()+ message_bus = _FakeMessageBus()+ storage = _LockAwareStorage(message_bus)+ closed_sessions: list[WebRTCSession] = []++ async def _create_agent() -> RealtimeAgent:+ return agent++ session = _make_session(+ transport=transport,+ peer_connection=peer_connection,+ agent_factory=_create_agent,+ storage=storage,+ message_bus=message_bus,+ on_closed=closed_sessions.append,+ )+ close_task: asyncio.Task[None] | None = None+ with patch("websockets.connect", AsyncMock(return_value=socket)):+ session.start()+ try:+ await asyncio.wait_for(socket.setup_sent.wait(), timeout=1)+ self.assertTrue(await session.wait_until_lock_acquired(1))+ close_task = asyncio.create_task(session.close())+ await asyncio.wait_for(asyncio.shield(close_task), timeout=1)+ self.assertTrue(socket.closed)+ self.assertIsNone(model._reader)+ self.assertTrue(peer_connection.closed)+ self.assertTrue(transport.closed)+ self.assertFalse(message_bus.held_locks)+ self.assertEqual(storage.writes_under_session_lock, [True])+ self.assertEqual(closed_sessions, [session])+ finally:+ if session._task is not None:+ session._task.cancel()+ await asyncio.gather(session._task, return_exceptions=True)+ if close_task is not None:+ await asyncio.gather(close_task, return_exceptions=True)+ await agent.close()++ async def test_repeated_close_does_not_cancel_startup_cleanup(+ self,+ ) -> None:+ """Concurrent close callers must share one startup cancellation."""+ entered = asyncio.Event()+ cleanup_entered = asyncio.Event()+ release_cleanup = asyncio.Event()+ cleanup_finished = asyncio.Event()+ message_bus = _FakeMessageBus()+ peer_connection = _FakePeerConnection()+ closed_sessions: list[WebRTCSession] = []++ async def _create_agent() -> _FakeAgent:+ entered.set()+ try:+ await asyncio.Event().wait()+ finally:+ cleanup_entered.set()+ await release_cleanup.wait()+ cleanup_finished.set()+ raise AssertionError("The blocked factory must be cancelled.")++ session = _make_session(+ peer_connection=peer_connection,+ agent_factory=_create_agent,+ storage=_FakeStorage(),+ message_bus=message_bus,+ on_closed=closed_sessions.append,+ )+ close_tasks: list[asyncio.Task[None]] = []+ session.start()+ try:+ await asyncio.wait_for(entered.wait(), timeout=1)+ close_tasks.append(asyncio.create_task(session.close()))+ await asyncio.wait_for(cleanup_entered.wait(), timeout=1)+ close_tasks.append(asyncio.create_task(session.close()))+ done, _ = await asyncio.wait(close_tasks, timeout=0.01)+ self.assertFalse(done)+ self.assertFalse(peer_connection.closed)+ release_cleanup.set()+ await asyncio.wait_for(asyncio.gather(*close_tasks), timeout=1)+ self.assertTrue(cleanup_finished.is_set())+ self.assertFalse(message_bus.held_locks)+ self.assertEqual(closed_sessions, [session])+ finally:+ release_cleanup.set()+ if session._task is not None:+ session._task.cancel()+ await asyncio.gather(session._task, return_exceptions=True)+ await asyncio.gather(*close_tasks, return_exceptions=True)++ async def test_cancelled_close_caller_keeps_final_persistence_alive(+ self,+ ) -> None:+ """Closing an active session waits for its owned persistence task."""+ write_entered = asyncio.Event()+ release_write = asyncio.Event()+ message_bus = _FakeMessageBus()+ peer_connection = _FakePeerConnection()+ closed_sessions: list[WebRTCSession] = []++ class BlockingStorage(_LockAwareStorage):+ """Hold the final write until the close callers are waiting."""++ async def update_session_state(self, **kwargs: object) -> None:+ """Wait before committing the owned final state snapshot."""+ write_entered.set()+ await release_write.wait()+ await super().update_session_state(**kwargs)++ storage = BlockingStorage(message_bus)+ agent = _FakeAgent({"id": "existing-message", "role": "assistant"}, [])++ async def _create_agent() -> _FakeAgent:+ return agent++ session = _make_session(+ peer_connection=peer_connection,+ agent_factory=_create_agent,+ storage=storage,+ message_bus=message_bus,+ on_closed=closed_sessions.append,+ )+ close_tasks: list[asyncio.Task[None]] = []+ session.start()+ try:+ await asyncio.wait_for(write_entered.wait(), timeout=1)+ close_tasks = [+ asyncio.create_task(session.close()),+ asyncio.create_task(session.close()),+ ]+ done, _ = await asyncio.wait(close_tasks, timeout=0.01)+ self.assertFalse(done)+ close_tasks[0].cancel()+ await asyncio.gather(close_tasks[0], return_exceptions=True)+ self.assertIsNotNone(session._task)+ self.assertFalse(session._task.done())+ self.assertIn(+ MessageBusKeys.session_lock("session-1"),+ message_bus.held_locks,+ )+ release_write.set()+ await asyncio.wait_for(close_tasks[1], timeout=1)+ self.assertEqual(storage.writes_under_session_lock, [True])+ self.assertFalse(message_bus.held_locks)+ self.assertTrue(peer_connection.closed)+ self.assertEqual(closed_sessions, [session])+ finally:+ release_write.set()+ if session._task is not None:+ session._task.cancel()+ await asyncio.gather(session._task, return_exceptions=True)+ await asyncio.gather(*close_tasks, return_exceptions=True)++ async def test_cancelled_close_caller_keeps_transport_cleanup_alive(+ self,+ ) -> None:+ """Caller cancellation must not strand a partially closed transport."""+ cleanup_entered = asyncio.Event()+ release_cleanup = asyncio.Event()+ transport = WebRTCAudioTransport(16_000, 24_000)+ peer_connection = _FakePeerConnection()+ closed_sessions: list[WebRTCSession] = []++ async def _read_input() -> None:+ try:+ await asyncio.Event().wait()+ finally:+ cleanup_entered.set()+ await release_cleanup.wait()++ transport._input_task = asyncio.create_task(_read_input())+ session = _make_session(+ transport=transport,+ peer_connection=peer_connection,+ agent_factory=AsyncMock(),+ storage=_FakeStorage(),+ message_bus=_BlockedMessageBus(),+ on_closed=closed_sessions.append,+ )+ session.start()+ close_tasks: list[asyncio.Task[None]] = []+ try:+ await asyncio.sleep(0)+ close_tasks.append(asyncio.create_task(session.close()))+ await asyncio.wait_for(cleanup_entered.wait(), timeout=1)+ close_tasks[0].cancel()+ await asyncio.gather(close_tasks[0], return_exceptions=True)+ close_tasks.append(asyncio.create_task(session.close()))+ release_cleanup.set()+ await asyncio.wait_for(asyncio.shield(close_tasks[1]), timeout=1)+ self.assertEqual(+ {+ "input_task": transport._input_task,+ "transport_closed": transport._closed,+ "peer_closed": peer_connection.closed,+ "closed_sessions": closed_sessions,+ },+ {+ "input_task": None,+ "transport_closed": True,+ "peer_closed": True,+ "closed_sessions": [session],+ },+ )+ finally:+ release_cleanup.set()+ if session._task is not None:+ session._task.cancel()+ await asyncio.gather(session._task, return_exceptions=True)+ await asyncio.gather(*close_tasks, return_exceptions=True)++ async def test_close_preserves_final_write_after_startup_failure(+ self,+ ) -> None:+ """Failed startup must finish persistence before releasing its lock."""+ write_entered = asyncio.Event()+ release_write = asyncio.Event()+ message_bus = _FakeMessageBus()+ closed_sessions: list[WebRTCSession] = []++ class BlockingStorage(_LockAwareStorage):+ """Pause the final write after startup has failed."""++ async def update_session_state(self, **kwargs: object) -> None:+ """Wait before committing the final snapshot."""+ write_entered.set()+ await release_write.wait()+ await super().update_session_state(**kwargs)++ agent = AsyncMock()+ agent.state = SimpleNamespace(context=[])+ agent.__aenter__.side_effect = RuntimeError("Setup failed.")+ storage = BlockingStorage(message_bus)+ session = _make_session(+ agent_factory=AsyncMock(return_value=agent),+ storage=storage,+ message_bus=message_bus,+ on_closed=closed_sessions.append,+ )+ session.start()+ close_task: asyncio.Task[None] | None = None+ try:+ await asyncio.wait_for(write_entered.wait(), timeout=1)+ close_task = asyncio.create_task(session.close())+ done, _ = await asyncio.wait([close_task], timeout=0.01)+ self.assertEqual(done, set())+ release_write.set()+ await asyncio.wait_for(asyncio.shield(close_task), timeout=1)+ self.assertEqual(+ storage.calls,+ [+ {+ "method": "update_session_state",+ "user_id": "alice",+ "agent_id": "agent-1",+ "session_id": "session-1",+ "state": agent.state,+ },+ ],+ )+ self.assertEqual(storage.writes_under_session_lock, [True])+ self.assertEqual(message_bus.held_locks, set())+ self.assertEqual(closed_sessions, [session])+ agent.close.assert_awaited_once_with()+ finally:+ release_write.set()+ if session._task is not None:+ await asyncio.gather(session._task, return_exceptions=True)+ if close_task is not None:+ await asyncio.gather(close_task, return_exceptions=True)+async def test_checkpoint_boundaries_persist_state(self) -> None:"""Persist tool boundaries but not ordinary text block endings."""message = {"id": "message-1", "role": "assistant"}