fix(startup): gate readiness on agent join, not audio-track subscription (#197)

Wait for the first remote participant to join before sending conversation_init,
instead of waiting for the agent's audio track to subscribe. Participant-join is
the direct "safe to send" signal; LiveKit auto-plays remote audio, so playback
never depended on the track-subscription wait.

LiveKitReadinessDelegate now resolves on roomDidConnect / participantDidConnect,
dropping the Stage machine, checkForSubscribedAudio, and didSubscribeTrack.
Internal-only, no public API change. Adds a signature-guard test for the
delegate's RoomDelegate methods.

Author: renal128

Sources/ElevenLabs/Internal/Networking/WebRTCConnectionManager.swift

@@ -133,7 +133,7 @@ final class WebRTCConnectionManager: WebRTCConnectionManaging {
         return StartupResult(agentId: auth.agentId, metrics: metrics)
     }
 
-    /// Race the delegate's "agent audio track subscribed" signal against `timeout`.
+    /// Race the delegate's "first remote participant joined" signal against `timeout`.
     /// A `.timedOut` result makes `connect` fail with `StartupFailure.agentTimeout`.
     private func waitForAgentReady(timeout: TimeInterval) async -> AgentReadyWaitResult {
         guard let delegate = readinessDelegate else {
@@ -143,7 +143,7 @@ final class WebRTCConnectionManager: WebRTCConnectionManaging {
         return await withTaskGroup(of: AgentReadyWaitResult.self) { group in
             group.addTask {
                 do {
-                    try await delegate.awaitSubscription()
+                    try await delegate.awaitRemoteParticipant()
                     return .success(elapsed: Date().timeIntervalSince(start))
                 } catch {
                     return .timedOut(elapsed: Date().timeIntervalSince(start))
@@ -321,6 +321,11 @@ final class WebRTCConnectionManager: WebRTCConnectionManaging {
     }
 }
 
+/// The agent joins with an identity prefixed `agent`; other participants don't.
+private func isAgentParticipant(_ participant: Participant) -> Bool {
+    (participant.identity.map { String(describing: $0) } ?? "").hasPrefix("agent")
+}
+
 // MARK: – Room event delegate
 
 /// `RoomDelegate` that forwards data, remote speaking, and remote-disconnect events
@@ -353,8 +358,7 @@ final class LiveKitRoomEventDelegate: RoomDelegate {
     }
 
     nonisolated func room(_ room: Room, participantDidDisconnect participant: RemoteParticipant) {
-        let identityString = participant.identity.map { String(describing: $0) } ?? ""
-        guard identityString.hasPrefix("agent") || room.remoteParticipants.isEmpty else { return }
+        guard isAgentParticipant(participant) || room.remoteParticipants.isEmpty else { return }
         Task { [onRemoteDisconnect] in
             await onRemoteDisconnect()
         }
@@ -370,101 +374,70 @@ final class LiveKitRoomEventDelegate: RoomDelegate {
 
 // MARK: – Readiness delegate
 
-/// Observes LiveKit and signals exactly one event: the agent's audio track is
-/// subscribed (the real "safe to send" signal). Holds no timing policy; callers
-/// race `awaitSubscription()` against their own timeout.
+/// Observes LiveKit and signals exactly one event: the first remote participant
+/// has joined the room (the "safe to send" signal). Holds no timing policy; callers
+/// race `awaitRemoteParticipant()` against their own timeout.
 @MainActor
-private final class LiveKitReadinessDelegate: RoomDelegate {
-    private enum Stage { case waiting, ready, released }
-
+final class LiveKitReadinessDelegate: RoomDelegate {
     private let logger: any Logging
-    private var stage: Stage = .waiting
-    private var awaiter: CheckedContinuation<Void, Error>?
+    private var continuation: CheckedContinuation<Void, Error>?
+    private var outcome: Result<Void, Error>?
 
     init(logger: any Logging) {
         self.logger = logger
     }
 
-    /// Suspend until the agent's audio track is subscribed. Throws `CancellationError`
+    /// Suspend until the first remote participant joins. Throws `CancellationError`
     /// if the awaiting task is cancelled or `release()` is called (e.g. on disconnect).
     /// Single-caller — there's exactly one `waitForAgentReady` per connection lifetime.
-    func awaitSubscription() async throws {
-        switch stage {
-        case .ready: return
-        case .released: throw CancellationError()
-        case .waiting: break
-        }
+    func awaitRemoteParticipant() async throws {
+        if let outcome { return try outcome.get() }
         try await withTaskCancellationHandler {
             try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
-                if Task.isCancelled {
+                if let outcome {
+                    cont.resume(with: outcome)
+                } else if Task.isCancelled {
                     cont.resume(throwing: CancellationError())
-                    return
-                }
-                switch stage {
-                case .ready: cont.resume()
-                case .released: cont.resume(throwing: CancellationError())
-                case .waiting: awaiter = cont
+                } else {
+                    continuation = cont
                 }
             }
         } onCancel: {
-            Task { @MainActor [weak self] in
-                if let cont = self?.awaiter {
-                    self?.awaiter = nil
-                    cont.resume(throwing: CancellationError())
-                }
-            }
+            Task { @MainActor [weak self] in self?.finish(.failure(CancellationError())) }
         }
     }
 
     /// Resolve the in-flight awaiter (if any) with `CancellationError`. Called by
     /// the manager on disconnect (or before swapping in a fresh delegate on reconnect).
     func release() {
-        guard stage != .released else { return }
-        stage = .released
-        if let cont = awaiter {
-            awaiter = nil
-            cont.resume(throwing: CancellationError())
-        }
+        finish(.failure(CancellationError()))
     }
 
     // MARK: - RoomDelegate
 
     nonisolated func roomDidConnect(_ room: Room) {
-        Task { @MainActor in self.checkForSubscribedAudio(in: room) }
-    }
-
-    nonisolated func room(_ room: Room, participantDidConnect _: RemoteParticipant) {
-        Task { @MainActor in self.checkForSubscribedAudio(in: room) }
+        Task { @MainActor in
+            if room.remoteParticipants.values.contains(where: isAgentParticipant) { self.markReady() }
+        }
     }
 
-    nonisolated func room(
-        _: Room,
-        participant _: RemoteParticipant,
-        didSubscribeTrack publication: RemoteTrackPublication
-    ) {
+    nonisolated func room(_: Room, participantDidConnect participant: RemoteParticipant) {
         Task { @MainActor in
-            guard publication.kind == .audio else { return }
-            self.markReady()
+            if isAgentParticipant(participant) { self.markReady() }
         }
     }
 
     // MARK: - Private
 
-    private func checkForSubscribedAudio(in room: Room) {
-        guard stage == .waiting else { return }
-        let hasSubscribed = room.remoteParticipants.values.contains { participant in
-            participant.audioTracks.contains { $0.isSubscribed && $0.track != nil }
-        }
-        if hasSubscribed { markReady() }
+    private func markReady() {
+        logger.debug("Agent joined")
+        finish(.success(()))
     }
 
-    private func markReady() {
-        guard stage == .waiting else { return }
-        stage = .ready
-        logger.debug("Agent audio track subscribed")
-        if let cont = awaiter {
-            awaiter = nil
-            cont.resume()
-        }
+    private func finish(_ result: Result<Void, Error>) {
+        guard outcome == nil else { return }
+        outcome = result
+        continuation?.resume(with: result)
+        continuation = nil
     }
 }

Tests/ElevenLabsTests/Unit/LiveKitReadinessDelegateTests.swift

@@ -0,0 +1,22 @@
+@testable import ElevenLabs
+import LiveKit
+import XCTest
+
+/// `RoomDelegate` methods are `@objc optional`, so a wrong signature compiles but
+/// is never called. These references only type-check against genuine requirements.
+@MainActor
+final class LiveKitReadinessDelegateTests: XCTestCase {
+    private func makeDelegate() -> RoomDelegate {
+        LiveKitReadinessDelegate(logger: SDKLogger(logLevel: .warning))
+    }
+
+    func testImplementsGenuineRoomDelegateMethods() {
+        let delegate = makeDelegate()
+
+        let onConnect: ((Room) -> Void)? = delegate.roomDidConnect
+        let onParticipantConnect: ((Room, RemoteParticipant) -> Void)? = delegate.room(_:participantDidConnect:)
+
+        XCTAssertNotNil(onConnect, "roomDidConnect must be a real RoomDelegate requirement")
+        XCTAssertNotNil(onParticipantConnect, "participantDidConnect must be a real RoomDelegate requirement")
+    }
+}