roomkit 0.77.0__tar.gz → 0.78.0__tar.gz

{roomkit-0.77.0 → roomkit-0.78.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roomkit
-Version: 0.77.0
+Version: 0.78.0
 Summary: Pure async Python library for multi-channel conversations
 Project-URL: Homepage, https://roomkit.live
 Project-URL: Documentation, https://www.roomkit.live/docs/

roomkit-0.78.0/src/roomkit/_version.py

@@ -0,0 +1 @@
+__version__ = "0.78.0"

{roomkit-0.77.0 → roomkit-0.78.0}/src/roomkit/channels/realtime_voice.py

@@ -5,16 +5,18 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import contextvars
+import inspect
 import logging
 import threading
+import time
 from collections.abc import Awaitable, Callable
 from concurrent.futures import ThreadPoolExecutor
 from copy import deepcopy
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
 from uuid import uuid4
 
-from roomkit.channels._realtime_audio import RealtimeAudioMixin
+from roomkit.channels._realtime_audio import _MAX_QUEUED_AUDIO_CHUNKS, RealtimeAudioMixin
 from roomkit.channels._realtime_context import (
     _current_voice_session as _current_voice_session,
 )
@@ -80,6 +82,15 @@ class _ConnectingSession:
 
     task: asyncio.Task[VoiceSession]
     disconnected: bool = False
+    deferred: bool = False
+    callbacks: list[tuple[Callable[..., Any], tuple[Any, ...]]] = field(default_factory=list)
+    audio_bytes: int = 0
+    failure: Exception | None = None
+
+    def fail(self, error: Exception) -> None:
+        self.failure = error
+        if not self.task.done() and not self.task.cancelling():
+            self.task.cancel()
 
 
 class RealtimeVoiceChannel(
@@ -511,16 +522,16 @@ class RealtimeVoiceChannel(
         self._turn_spans: dict[str, str] = {}
 
         # Wire internal callbacks
-        provider.on_audio(self._on_provider_audio)
-        provider.on_transcription(self._on_provider_transcription)
-        provider.on_transcription(self._on_transcript_fragment)
-        provider.on_speech_start(self._on_provider_speech_start)
-        provider.on_speech_end(self._on_provider_speech_end)
-        provider.on_tool_call(self._on_provider_tool_call)
-        provider.on_delegation(self._on_provider_delegation)
-        provider.on_response_start(self._on_provider_response_start)
-        provider.on_response_end(self._on_provider_response_end)
-        provider.on_error(self._on_provider_error)
+        provider.on_audio(self._gate_provider_callback(self._on_provider_audio))
+        provider.on_transcription(self._gate_provider_callback(self._on_provider_transcription))
+        provider.on_transcription(self._gate_provider_callback(self._on_transcript_fragment))
+        provider.on_speech_start(self._gate_provider_callback(self._on_provider_speech_start))
+        provider.on_speech_end(self._gate_provider_callback(self._on_provider_speech_end))
+        provider.on_tool_call(self._gate_provider_callback(self._on_provider_tool_call))
+        provider.on_delegation(self._gate_provider_callback(self._on_provider_delegation))
+        provider.on_response_start(self._gate_provider_callback(self._on_provider_response_start))
+        provider.on_response_end(self._gate_provider_callback(self._on_provider_response_end))
+        provider.on_error(self._on_startup_provider_error)
 
         # Direct audio path: only when no pipeline is configured.
         # When pipeline= is set, _create_pipeline() registers
@@ -1001,7 +1012,16 @@ class RealtimeVoiceChannel(
         Args:
             room_id: The room to join.
             participant_id: The participant's ID.
-            connection: Protocol-specific connection (e.g. WebSocket).
+            connection: Protocol-specific connection (e.g. WebSocket), or an
+                awaitable resolving to it. With an awaitable, provider setup
+                starts while the connection is pending (e.g. SIP ringing).
+                Cancel the start task if the connection will never arrive.
+                Both branches belong to this session and are rolled back on
+                failure. The channel publishes the session only when both are ready.
+                Provider callbacks wait for publication in a bounded startup
+                queue; exceeding 2 MiB of audio or 500 events aborts startup.
+                Monotonic timestamps are written to metadata's
+                ``connection_timing`` for measuring setup and pre-answer cost.
             metadata: Optional session metadata. May include overrides
                 for system_prompt, voice, tools, temperature.
 
@@ -1021,7 +1041,7 @@ class RealtimeVoiceChannel(
         task = asyncio.create_task(
             self._start_session(session, connection), name=f"rt_connect:{session.id}"
         )
-        pending = _ConnectingSession(task)
+        pending = _ConnectingSession(task, deferred=inspect.isawaitable(connection))
         self._connecting_sessions[session.id] = pending
         try:
             return await task
@@ -1036,6 +1056,9 @@ class RealtimeVoiceChannel(
                 await _finish_cleanup(self.end_session(session))
             else:
                 await _finish_cleanup(self._cleanup_failed_start(session))
+            pending = self._connecting_sessions.get(session.id)
+            if pending is not None and pending.failure is not None:
+                raise pending.failure from None
             raise
 
     async def _cleanup_failed_start(self, session: VoiceSession) -> None:
@@ -1087,6 +1110,8 @@ class RealtimeVoiceChannel(
         room_id, participant_id = session.room_id, session.participant_id
         self._session_config_locks[session.id] = asyncio.Lock()
         meta = session.metadata
+        timing: dict[str, float] = {}
+        meta["connection_timing"] = timing
         # Start telemetry session span early so transport/provider connect
         # phases appear as children in Jaeger.
         telemetry = self._telemetry_provider
@@ -1179,56 +1204,89 @@ class RealtimeVoiceChannel(
         if self._pipeline is not None:
             self._pipeline_session_active(session)
 
-        with telemetry.span(
-            SpanKind.BACKEND_CONNECT,
-            "transport.accept",
-            parent_id=session_span_id,
-            session_id=session.id,
-            attributes={Attr.BACKEND_TYPE: self._transport.name},
-        ):
-            await self._transport.accept(session, connection)
-        self._check_connecting_session(session)
-
-        # Connect to provider (with telemetry span).
-        # If provider.connect fails, clean up the already-accepted transport
-        # session to avoid leaking the connection.
-        try:
-            self._prepare_session_audio(session)
+        async def accept_transport() -> None:
+            resolved = await connection if inspect.isawaitable(connection) else connection
+            self._check_connecting_session(session)
             with telemetry.span(
                 SpanKind.BACKEND_CONNECT,
-                "provider.connect",
+                "transport.accept",
                 parent_id=session_span_id,
                 session_id=session.id,
-                attributes={Attr.BACKEND_TYPE: self._provider.name},
+                attributes={Attr.BACKEND_TYPE: self._transport.name},
             ):
-                await self._provider.connect(
-                    session,
-                    system_prompt=system_prompt,
-                    voice=voice,
-                    tools=tools,
-                    temperature=temperature,
-                    input_sample_rate=self._input_sample_rate,
-                    output_sample_rate=self._output_sample_rate,
-                    server_vad=self._provider.full_duplex or not has_pipeline_vad,
-                    provider_config=provider_config,
-                )
-        except (Exception, asyncio.CancelledError) as exc:
-            # CancelledError here is the orchestrator deliberately aborting
-            # a still-handshaking session (e.g. carrier hung up before the
-            # provider WS connected). It's expected control flow, not a
-            # bug — log it as info without a traceback so dashboards stay
-            # quiet. Real failures keep their full stack trace.
-            if isinstance(exc, asyncio.CancelledError):
+                await self._transport.accept(session, resolved)
+            self._check_connecting_session(session)
+            self._prepare_session_audio(session)
+            timing["transport_ready_at"] = time.monotonic()
+
+        async def connect_provider() -> None:
+            # Connect to provider (with telemetry span).
+            # If provider.connect fails, clean up the already-accepted transport
+            # session to avoid leaking the connection.
+            try:
+                timing["provider_connect_started_at"] = time.monotonic()
+                with telemetry.span(
+                    SpanKind.BACKEND_CONNECT,
+                    "provider.connect",
+                    parent_id=session_span_id,
+                    session_id=session.id,
+                    attributes={Attr.BACKEND_TYPE: self._provider.name},
+                ):
+                    await self._provider.connect(
+                        session,
+                        system_prompt=system_prompt,
+                        voice=voice,
+                        tools=tools,
+                        temperature=temperature,
+                        input_sample_rate=self._input_sample_rate,
+                        output_sample_rate=self._output_sample_rate,
+                        server_vad=self._provider.full_duplex or not has_pipeline_vad,
+                        provider_config=provider_config,
+                    )
+                timing["provider_ready_at"] = time.monotonic()
                 logger.info(
-                    "provider.connect cancelled for session %s — transport cleaned up",
-                    session.id,
-                )
-            else:
-                logger.exception(
-                    "provider.connect failed for session %s; cleaned up transport",
+                    "Realtime provider ready: room=%s session=%s connect_ms=%.1f",
+                    room_id,
                     session.id,
+                    (timing["provider_ready_at"] - timing["provider_connect_started_at"]) * 1000,
                 )
-            raise
+            except (Exception, asyncio.CancelledError) as exc:
+                # CancelledError here is the orchestrator deliberately aborting
+                # a still-handshaking session (e.g. carrier hung up before the
+                # provider WS connected). It's expected control flow, not a
+                # bug — log it as info without a traceback so dashboards stay
+                # quiet. Real failures keep their full stack trace.
+                if isinstance(exc, asyncio.CancelledError):
+                    logger.info(
+                        "provider.connect cancelled for session %s — transport cleaned up",
+                        session.id,
+                    )
+                else:
+                    logger.exception(
+                        "provider.connect failed for session %s; cleaned up transport",
+                        session.id,
+                    )
+                raise
+
+        if inspect.isawaitable(connection):
+            # One handshake owns both branches. gather alone would leave its
+            # sibling running after an error; drain both before rollback.
+            branches = [
+                asyncio.create_task(accept_transport(), name=f"rt_transport:{session.id}"),
+                asyncio.create_task(connect_provider(), name=f"rt_provider:{session.id}"),
+            ]
+            try:
+                await asyncio.gather(*branches)
+            finally:
+                for branch in branches:
+                    if not branch.done():
+                        branch.cancel()
+                await asyncio.gather(*branches, return_exceptions=True)
+        else:
+            # Preserve ordinary startup ordering, including codec validation
+            # before any provider connection is opened.
+            await accept_transport()
+            await connect_provider()
 
         self._check_connecting_session(session)
         session.state = VoiceSessionState.ACTIVE
@@ -1237,6 +1295,12 @@ class RealtimeVoiceChannel(
             self._session_rooms[session.id] = room_id
 
         await self._finish_session_start(session, room_id, participant_id)
+        self._check_connecting_session(session)
+        pending = self._connecting_sessions[session.id]
+        pending.deferred = False
+        for callback, args in pending.callbacks:
+            callback(*args)
+        pending.callbacks.clear()
 
         return session
 
@@ -1760,6 +1824,41 @@ class RealtimeVoiceChannel(
 
     # -- Internal callbacks --
 
+    def _gate_provider_callback(self, callback: Callable[..., Any]) -> Callable[..., Any]:
+        """Keep startup events ordered until transport and authorization are ready.
+
+        No application task runs while SIP is ringing. Audio enters the normal
+        send FIFO only after the negotiated codec and binding are available.
+        Rollback discards the journal with its connecting-session owner.
+        """
+
+        def dispatch(session: VoiceSession, *args: Any) -> Any:
+            pending = self._connecting_sessions.get(session.id)
+            if pending is None or not pending.deferred:
+                return callback(session, *args)
+            if pending.failure is not None or pending.task.cancelling():
+                return None
+            size = sum(len(arg) for arg in args if isinstance(arg, bytes))
+            if (
+                len(pending.callbacks) >= _MAX_QUEUED_AUDIO_CHUNKS
+                or pending.audio_bytes + size > 2 * 1024 * 1024
+            ):
+                pending.fail(RuntimeError("Provider startup event buffer exceeded"))
+                return None
+            pending.audio_bytes += size
+            pending.callbacks.append((callback, (session, *args)))
+            return None
+
+        return dispatch
+
+    def _on_startup_provider_error(self, session: VoiceSession, code: str, message: str) -> Any:
+        pending = self._connecting_sessions.get(session.id)
+        if pending is not None and session.state == VoiceSessionState.ENDED:
+            pending.fail(RuntimeError(f"Provider connection failed [{code}]: {message}"))
+            self._announce_provider_error(session, code, message)
+            return None
+        return self._on_provider_error(session, code, message)
+
     def _on_client_disconnected(self, session: VoiceSession) -> Any:
         """Handle client disconnection — end the session."""
         try:

{roomkit-0.77.0 → roomkit-0.78.0}/src/roomkit/core/mixins/voice_ops.py

@@ -122,7 +122,11 @@ class VoiceOpsMixin(HelpersMixin):
                 so the bridge sends audio through the correct transport.
             connection: Protocol-specific connection for realtime voice
                 channels (e.g. WebSocket).  Required when joining a
-                :class:`RealtimeVoiceChannel`.
+                :class:`RealtimeVoiceChannel`. May be an awaitable resolving
+                to that connection: provider setup then overlaps the wait,
+                under the same cancellable join. Bound that wait at the call
+                site (e.g. the dial timeout); no active session or started hook
+                is exposed until both transport and provider are ready.
 
         Returns:
             The voice or video session (created or passed in).

{roomkit-0.77.0 → roomkit-0.78.0}/src/roomkit/voice/backends/sip_calling.py

@@ -857,6 +857,7 @@ class SIPCallingMixin:
                 )
 
             await out_call.wait_answered(timeout=timeout)
+            sip_answered_at = time.monotonic()
             setup.answered = True
 
             # Map call_id early so re-INVITEs arriving during RTP setup are
@@ -908,6 +909,7 @@ class SIPCallingMixin:
                     "callee": to_uri,
                     "room_id": effective_room_id,
                     "direction": "outbound",
+                    "sip_answered_at": sip_answered_at,
                     "input_sample_rate": actual_codec_rate,
                     "output_sample_rate": actual_codec_rate,
                     "codec_sample_rate": actual_codec_rate,

{roomkit-0.77.0 → roomkit-0.78.0}/tests/test_realtime_deepgram.py

@@ -1356,7 +1356,8 @@ class TestChannelIntegration:
 
         await channel.end_session(session)
 
-    async def test_greeting_audio_during_handshake_reaches_transport(self) -> None:
+    @pytest.mark.parametrize("deferred", [False, True])
+    async def test_greeting_audio_during_handshake_reaches_transport(self, deferred: bool) -> None:
         """Early greeting callbacks wait until the channel publishes the session."""
         provider = DeepgramAgentProvider(DeepgramAgentConfig(api_key=SecretStr("dg")))
         transport = MockRealtimeTransport()
@@ -1380,7 +1381,20 @@ class TestChannelIntegration:
             ]
         )
         with patch("websockets.connect", AsyncMock(return_value=ws)):
-            session = await channel.start_session(room.id, "user-1", "fake-ws")
+            if deferred:
+                connection = asyncio.get_running_loop().create_future()
+                start = asyncio.create_task(channel.start_session(room.id, "user-1", connection))
+                while (
+                    not provider._states
+                    or not next(iter(provider._states.values())).callbacks_ready
+                ):
+                    await asyncio.sleep(0)
+                await asyncio.sleep(0)
+                assert not transport.sent_audio
+                connection.set_result("fake-ws")
+                session = await start
+            else:
+                session = await channel.start_session(room.id, "user-1", "fake-ws")
 
         for _ in range(100):
             if transport.sent_audio:
@@ -1389,3 +1403,22 @@ class TestChannelIntegration:
 
         assert transport.sent_audio == [(session.id, b"greeting-audio")]
         await channel.end_session(session)
+
+
+async def test_fatal_deepgram_close_aborts_deferred_transport() -> None:
+    provider = DeepgramAgentProvider(DeepgramAgentConfig(api_key=SecretStr("test")))
+    transport = MockRealtimeTransport()
+    channel = RealtimeVoiceChannel("rt", provider=provider, transport=transport)
+    ws = _FakeWS()
+    connection = asyncio.get_running_loop().create_future()
+    with patch("websockets.connect", AsyncMock(return_value=ws)):
+        start = asyncio.create_task(channel.start_session("r", "p", connection))
+        while not provider._states or not next(iter(provider._states.values())).callbacks_ready:
+            await asyncio.sleep(0)
+        ws.finish()
+        with pytest.raises(RuntimeError, match="Provider connection failed"):
+            await asyncio.wait_for(start, 1)
+    assert connection.cancelled()
+    assert not provider._states and not channel._connecting_sessions
+    assert not channel.get_room_sessions("r")
+    await channel.close()