From 2e927a7f5585d74d269a08c71c667db45322a19f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Tue, 16 Sep 2025 10:48:02 +0200
Subject: [PATCH 01/28] Basic providers with cache

---
 .../LiveKit/Auth/ConnectionCredentials.swift  | 160 ++++++++++++++++++
 Sources/LiveKit/Core/Room.swift               |   8 +
 2 files changed, 168 insertions(+)
 create mode 100644 Sources/LiveKit/Auth/ConnectionCredentials.swift

diff --git a/Sources/LiveKit/Auth/ConnectionCredentials.swift b/Sources/LiveKit/Auth/ConnectionCredentials.swift
new file mode 100644
index 000000000..6853ae044
--- /dev/null
+++ b/Sources/LiveKit/Auth/ConnectionCredentials.swift
@@ -0,0 +1,160 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Foundation
+
+public enum ConnectionCredentials {
+    public struct Request: Encodable, Equatable, Sendable {
+        let roomName: String? = nil
+        let participantName: String? = nil
+        let participantIdentity: String? = nil
+        let participantMetadata: String? = nil
+        let participantAttributes: [String: String]? = nil
+//        let roomConfiguration: RoomConfiguration? = nil
+    }
+
+    public struct Response: Decodable, Sendable {
+        let serverUrl: URL
+        let participantToken: String
+    }
+
+    public typealias Literal = Response
+}
+
+// MARK: - Provider
+
+public protocol CredentialsProvider: Sendable {
+    func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response
+}
+
+// MARK: - Implementation
+
+extension ConnectionCredentials.Literal: CredentialsProvider {
+    public func fetch(_: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
+        self
+    }
+}
+
+public struct SandboxTokenServer: CredentialsProvider, Loggable {
+    private static let baseURL = URL(string: "https://cloud-api.livekit.io")!
+
+    public struct Options: Sendable {
+        let id: String
+        let baseURL: URL? = nil
+    }
+
+    private let options: Options
+
+    public init(options: Options) {
+        self.options = options
+    }
+
+    public init(id: String) {
+        options = .init(id: id)
+    }
+
+    public func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
+        log("Using sandbox token server is not applicable for production environemnt", .info)
+
+        let baseURL = options.baseURL ?? Self.baseURL
+        var urlRequest = URLRequest(url: baseURL.appendingPathComponent("api/sandbox/connection-details"))
+
+        urlRequest.httpMethod = "POST"
+        urlRequest.addValue(options.id.trimmingCharacters(in: CharacterSet(charactersIn: "\"")), forHTTPHeaderField: "X-Sandbox-ID")
+        urlRequest.httpBody = try JSONEncoder().encode(request)
+
+        let (data, response) = try await URLSession.shared.data(for: urlRequest)
+
+        guard let httpResponse = response as? HTTPURLResponse else {
+            throw LiveKitError(.network, message: "Error generating token from sandbox token server, no response")
+        }
+
+        guard (200 ... 299).contains(httpResponse.statusCode) else {
+            throw LiveKitError(.network, message: "Error generating token from sandbox token server, received \(httpResponse)")
+        }
+
+        return try JSONDecoder().decode(ConnectionCredentials.Response.self, from: data)
+    }
+}
+
+// MARK: - Cache
+
+public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
+    private let provider: CredentialsProvider
+    private let validator: (ConnectionCredentials.Request, ConnectionCredentials.Response) -> Bool
+
+    private var cached: (ConnectionCredentials.Request, ConnectionCredentials.Response)?
+
+    public init(_ provider: CredentialsProvider, validator: @escaping (ConnectionCredentials.Request, ConnectionCredentials.Response) -> Bool = { _, res in res.hasValidToken() }) {
+        self.provider = provider
+        self.validator = validator
+    }
+
+    public func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
+        if let (cachedRequest, cachedResponse) = cached, cachedRequest == request, validator(cachedRequest, cachedResponse) {
+            log("Using cached credentials", .debug)
+            return cachedResponse
+        }
+
+        let response = try await provider.fetch(request)
+        cached = (request, response)
+        return response
+    }
+
+    public func invalidate() {
+        cached = nil
+    }
+}
+
+// MARK: - Validation
+
+public extension ConnectionCredentials.Response {
+    func hasValidToken(withTolerance tolerance: TimeInterval = 60) -> Bool {
+        let parts = participantToken.components(separatedBy: ".")
+        guard parts.count == 3 else {
+            return false
+        }
+
+        let payloadData = parts[1]
+
+        struct JWTPayload: Decodable {
+            let exp: Double
+        }
+
+        guard let payloadJSON = payloadData.base64URLDecode(),
+              let payload = try? JSONDecoder().decode(JWTPayload.self, from: payloadJSON)
+        else {
+            return false
+        }
+
+        let now = Date().timeIntervalSince1970
+        return payload.exp > now - tolerance
+    }
+}
+
+private extension String {
+    func base64URLDecode() -> Data? {
+        var base64 = self
+        base64 = base64.replacingOccurrences(of: "-", with: "+")
+        base64 = base64.replacingOccurrences(of: "_", with: "/")
+
+        while base64.count % 4 != 0 {
+            base64.append("=")
+        }
+
+        return Data(base64Encoded: base64)
+    }
+}
diff --git a/Sources/LiveKit/Core/Room.swift b/Sources/LiveKit/Core/Room.swift
index 2d1675494..667c44371 100644
--- a/Sources/LiveKit/Core/Room.swift
+++ b/Sources/LiveKit/Core/Room.swift
@@ -408,6 +408,14 @@ public class Room: NSObject, @unchecked Sendable, ObservableObject, Loggable {
         log("Connected to \(String(describing: self))", .info)
     }
 
+    public func connect(credentialsProvider: CredentialsProvider,
+                        connectOptions: ConnectOptions? = nil,
+                        roomOptions: RoomOptions? = nil) async throws
+    {
+        let credentials = try await credentialsProvider.fetch(.init())
+        try await connect(url: credentials.serverUrl.absoluteString, token: credentials.participantToken, connectOptions: connectOptions, roomOptions: roomOptions)
+    }
+
     @objc
     public func disconnect() async {
         // Return if already disconnected state

From fdf8c7f533b692b62cbe2c706a58a21495e67eff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Tue, 16 Sep 2025 11:04:31 +0200
Subject: [PATCH 02/28] Split token server

---
 .../LiveKit/Auth/ConnectionCredentials.swift  | 52 ++++++++++---------
 1 file changed, 28 insertions(+), 24 deletions(-)

diff --git a/Sources/LiveKit/Auth/ConnectionCredentials.swift b/Sources/LiveKit/Auth/ConnectionCredentials.swift
index 6853ae044..f4bb81919 100644
--- a/Sources/LiveKit/Auth/ConnectionCredentials.swift
+++ b/Sources/LiveKit/Auth/ConnectionCredentials.swift
@@ -40,40 +40,31 @@ public protocol CredentialsProvider: Sendable {
     func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response
 }
 
-// MARK: - Implementation
-
 extension ConnectionCredentials.Literal: CredentialsProvider {
     public func fetch(_: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
         self
     }
 }
 
-public struct SandboxTokenServer: CredentialsProvider, Loggable {
-    private static let baseURL = URL(string: "https://cloud-api.livekit.io")!
-
-    public struct Options: Sendable {
-        let id: String
-        let baseURL: URL? = nil
-    }
+// MARK: - Token Server
 
-    private let options: Options
-
-    public init(options: Options) {
-        self.options = options
-    }
-
-    public init(id: String) {
-        options = .init(id: id)
-    }
+public protocol TokenServer: CredentialsProvider {
+    var url: URL { get }
+    var method: String { get }
+    var headers: [String: String] { get }
+}
 
-    public func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
-        log("Using sandbox token server is not applicable for production environemnt", .info)
+public extension TokenServer {
+    var method: String { "POST" }
+    var headers: [String: String] { [:] }
 
-        let baseURL = options.baseURL ?? Self.baseURL
-        var urlRequest = URLRequest(url: baseURL.appendingPathComponent("api/sandbox/connection-details"))
+    func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
+        var urlRequest = URLRequest(url: url)
 
-        urlRequest.httpMethod = "POST"
-        urlRequest.addValue(options.id.trimmingCharacters(in: CharacterSet(charactersIn: "\"")), forHTTPHeaderField: "X-Sandbox-ID")
+        urlRequest.httpMethod = method
+        for (key, value) in headers {
+            urlRequest.addValue(value, forHTTPHeaderField: key)
+        }
         urlRequest.httpBody = try JSONEncoder().encode(request)
 
         let (data, response) = try await URLSession.shared.data(for: urlRequest)
@@ -90,6 +81,19 @@ public struct SandboxTokenServer: CredentialsProvider, Loggable {
     }
 }
 
+public struct SandboxTokenServer: TokenServer {
+    public let url = URL(string: "https://cloud-api.livekit.io/api/sandbox/connection-details")!
+    public var headers: [String: String] {
+        ["X-Sandbox-ID": id.trimmingCharacters(in: CharacterSet(charactersIn: "\""))]
+    }
+
+    public let id: String
+
+    public init(id: String) {
+        self.id = id
+    }
+}
+
 // MARK: - Cache
 
 public actor CachingCredentialsProvider: CredentialsProvider, Loggable {

From eb61eb3cf587a260d4c3a73fe85bf3e3762bc210 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Tue, 16 Sep 2025 11:28:37 +0200
Subject: [PATCH 03/28] Pass options

---
 .../LiveKit/Auth/ConnectionCredentials.swift  | 26 ++++++++++++++-----
 Sources/LiveKit/Core/Room.swift               |  3 ++-
 2 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/Sources/LiveKit/Auth/ConnectionCredentials.swift b/Sources/LiveKit/Auth/ConnectionCredentials.swift
index f4bb81919..e63dd74b1 100644
--- a/Sources/LiveKit/Auth/ConnectionCredentials.swift
+++ b/Sources/LiveKit/Auth/ConnectionCredentials.swift
@@ -18,19 +18,33 @@ import Foundation
 
 public enum ConnectionCredentials {
     public struct Request: Encodable, Equatable, Sendable {
-        let roomName: String? = nil
-        let participantName: String? = nil
-        let participantIdentity: String? = nil
-        let participantMetadata: String? = nil
-        let participantAttributes: [String: String]? = nil
-//        let roomConfiguration: RoomConfiguration? = nil
+        let roomName: String?
+        let participantName: String?
+        let participantIdentity: String?
+        let participantMetadata: String?
+        let participantAttributes: [String: String]?
+//        let roomConfiguration: RoomConfiguration?
+
+        public init(roomName: String? = nil, participantName: String? = nil, participantIdentity: String? = nil, participantMetadata: String? = nil, participantAttributes: [String: String]? = nil) {
+            self.roomName = roomName
+            self.participantName = participantName
+            self.participantIdentity = participantIdentity
+            self.participantMetadata = participantMetadata
+            self.participantAttributes = participantAttributes
+        }
     }
 
     public struct Response: Decodable, Sendable {
         let serverUrl: URL
         let participantToken: String
+
+        public init(serverUrl: URL, participantToken: String) {
+            self.serverUrl = serverUrl
+            self.participantToken = participantToken
+        }
     }
 
+    public typealias Options = Request
     public typealias Literal = Response
 }
 
diff --git a/Sources/LiveKit/Core/Room.swift b/Sources/LiveKit/Core/Room.swift
index 667c44371..eeceb2f9e 100644
--- a/Sources/LiveKit/Core/Room.swift
+++ b/Sources/LiveKit/Core/Room.swift
@@ -409,10 +409,11 @@ public class Room: NSObject, @unchecked Sendable, ObservableObject, Loggable {
     }
 
     public func connect(credentialsProvider: CredentialsProvider,
+                        credentialsOptions: ConnectionCredentials.Options = .init(),
                         connectOptions: ConnectOptions? = nil,
                         roomOptions: RoomOptions? = nil) async throws
     {
-        let credentials = try await credentialsProvider.fetch(.init())
+        let credentials = try await credentialsProvider.fetch(credentialsOptions)
         try await connect(url: credentials.serverUrl.absoluteString, token: credentials.participantToken, connectOptions: connectOptions, roomOptions: roomOptions)
     }
 

From aaf94aa728f26cd06e85c937839def594e3a1cb7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Tue, 16 Sep 2025 11:58:41 +0200
Subject: [PATCH 04/28] Expose RoomConfiguration (without pb)

---
 .../LiveKit/Auth/ConnectionCredentials.swift  |  22 ++--
 Sources/LiveKit/Types/RoomConfiguration.swift | 102 ++++++++++++++++++
 2 files changed, 118 insertions(+), 6 deletions(-)
 create mode 100644 Sources/LiveKit/Types/RoomConfiguration.swift

diff --git a/Sources/LiveKit/Auth/ConnectionCredentials.swift b/Sources/LiveKit/Auth/ConnectionCredentials.swift
index e63dd74b1..1fb84b0fc 100644
--- a/Sources/LiveKit/Auth/ConnectionCredentials.swift
+++ b/Sources/LiveKit/Auth/ConnectionCredentials.swift
@@ -17,20 +17,28 @@
 import Foundation
 
 public enum ConnectionCredentials {
-    public struct Request: Encodable, Equatable, Sendable {
+    public struct Request: Encodable, Sendable, Equatable {
         let roomName: String?
         let participantName: String?
         let participantIdentity: String?
         let participantMetadata: String?
         let participantAttributes: [String: String]?
-//        let roomConfiguration: RoomConfiguration?
-
-        public init(roomName: String? = nil, participantName: String? = nil, participantIdentity: String? = nil, participantMetadata: String? = nil, participantAttributes: [String: String]? = nil) {
+        let roomConfiguration: RoomConfiguration?
+
+        public init(
+            roomName: String? = nil,
+            participantName: String? = nil,
+            participantIdentity: String? = nil,
+            participantMetadata: String? = nil,
+            participantAttributes: [String: String]? = nil,
+            roomConfiguration: RoomConfiguration? = nil
+        ) {
             self.roomName = roomName
             self.participantName = participantName
             self.participantIdentity = participantIdentity
             self.participantMetadata = participantMetadata
             self.participantAttributes = participantAttributes
+            self.roomConfiguration = roomConfiguration
         }
     }
 
@@ -111,12 +119,14 @@ public struct SandboxTokenServer: TokenServer {
 // MARK: - Cache
 
 public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
+    public typealias Validator = (ConnectionCredentials.Request, ConnectionCredentials.Response) -> Bool
+
     private let provider: CredentialsProvider
-    private let validator: (ConnectionCredentials.Request, ConnectionCredentials.Response) -> Bool
+    private let validator: Validator
 
     private var cached: (ConnectionCredentials.Request, ConnectionCredentials.Response)?
 
-    public init(_ provider: CredentialsProvider, validator: @escaping (ConnectionCredentials.Request, ConnectionCredentials.Response) -> Bool = { _, res in res.hasValidToken() }) {
+    public init(_ provider: CredentialsProvider, validator: @escaping Validator = { _, res in res.hasValidToken() }) {
         self.provider = provider
         self.validator = validator
     }
diff --git a/Sources/LiveKit/Types/RoomConfiguration.swift b/Sources/LiveKit/Types/RoomConfiguration.swift
new file mode 100644
index 000000000..6e54a768b
--- /dev/null
+++ b/Sources/LiveKit/Types/RoomConfiguration.swift
@@ -0,0 +1,102 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Foundation
+
+public struct RoomConfiguration: Encodable, Sendable, Equatable {
+    /// Room name, used as ID, must be unique
+    public let name: String?
+
+    /// Number of seconds to keep the room open if no one joins
+    public let emptyTimeout: UInt32?
+
+    /// Number of seconds to keep the room open after everyone leaves
+    public let departureTimeout: UInt32?
+
+    /// Limit number of participants that can be in a room, excluding Egress and Ingress participants
+    public let maxParticipants: UInt32?
+
+    /// Metadata of room
+    public let metadata: String?
+
+    /// Minimum playout delay of subscriber
+    public let minPlayoutDelay: UInt32?
+
+    /// Maximum playout delay of subscriber
+    public let maxPlayoutDelay: UInt32?
+
+    /// Improves A/V sync when playout_delay set to a value larger than 200ms.
+    /// It will disable transceiver re-use so not recommended for rooms with frequent subscription changes
+    public let syncStreams: Bool?
+
+    /// Define agents that should be dispatched to this room
+    public let agents: [RoomAgentDispatch]?
+
+    enum CodingKeys: String, CodingKey {
+        case name
+        case emptyTimeout = "empty_timeout"
+        case departureTimeout = "departure_timeout"
+        case maxParticipants = "max_participants"
+        case metadata
+        case minPlayoutDelay = "min_playout_delay"
+        case maxPlayoutDelay = "max_playout_delay"
+        case syncStreams = "sync_streams"
+        case agents
+    }
+
+    public init(
+        name: String? = nil,
+        emptyTimeout: UInt32? = nil,
+        departureTimeout: UInt32? = nil,
+        maxParticipants: UInt32? = nil,
+        metadata: String? = nil,
+        minPlayoutDelay: UInt32? = nil,
+        maxPlayoutDelay: UInt32? = nil,
+        syncStreams: Bool? = nil,
+        agents: [RoomAgentDispatch]? = nil
+    ) {
+        self.name = name
+        self.emptyTimeout = emptyTimeout
+        self.departureTimeout = departureTimeout
+        self.maxParticipants = maxParticipants
+        self.metadata = metadata
+        self.minPlayoutDelay = minPlayoutDelay
+        self.maxPlayoutDelay = maxPlayoutDelay
+        self.syncStreams = syncStreams
+        self.agents = agents
+    }
+}
+
+public struct RoomAgentDispatch: Encodable, Sendable, Equatable {
+    /// Name of the agent to dispatch
+    public let agentName: String?
+
+    /// Metadata for the agent
+    public let metadata: String?
+
+    enum CodingKeys: String, CodingKey {
+        case agentName = "agent_name"
+        case metadata
+    }
+
+    public init(
+        agentName: String? = nil,
+        metadata: String? = nil
+    ) {
+        self.agentName = agentName
+        self.metadata = metadata
+    }
+}

From 19f79c82686c5440732f0c812d5fe6bec118ea7d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Tue, 16 Sep 2025 13:10:16 +0200
Subject: [PATCH 05/28] Add some tests

---
 .../LiveKit/Auth/ConnectionCredentials.swift  |  10 +-
 .../ConnectionCredentialsTests.swift          | 267 ++++++++++++++++++
 2 files changed, 273 insertions(+), 4 deletions(-)
 create mode 100644 Tests/LiveKitTests/ConnectionCredentialsTests.swift

diff --git a/Sources/LiveKit/Auth/ConnectionCredentials.swift b/Sources/LiveKit/Auth/ConnectionCredentials.swift
index 1fb84b0fc..62df4703a 100644
--- a/Sources/LiveKit/Auth/ConnectionCredentials.swift
+++ b/Sources/LiveKit/Auth/ConnectionCredentials.swift
@@ -119,12 +119,13 @@ public struct SandboxTokenServer: TokenServer {
 // MARK: - Cache
 
 public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
+    public typealias Cached = (ConnectionCredentials.Request, ConnectionCredentials.Response)
     public typealias Validator = (ConnectionCredentials.Request, ConnectionCredentials.Response) -> Bool
 
     private let provider: CredentialsProvider
     private let validator: Validator
 
-    private var cached: (ConnectionCredentials.Request, ConnectionCredentials.Response)?
+    private var cached: Cached?
 
     public init(_ provider: CredentialsProvider, validator: @escaping Validator = { _, res in res.hasValidToken() }) {
         self.provider = provider
@@ -159,22 +160,23 @@ public extension ConnectionCredentials.Response {
         let payloadData = parts[1]
 
         struct JWTPayload: Decodable {
+            let nbf: Double
             let exp: Double
         }
 
-        guard let payloadJSON = payloadData.base64URLDecode(),
+        guard let payloadJSON = payloadData.base64Decode(),
               let payload = try? JSONDecoder().decode(JWTPayload.self, from: payloadJSON)
         else {
             return false
         }
 
         let now = Date().timeIntervalSince1970
-        return payload.exp > now - tolerance
+        return payload.nbf <= now && payload.exp > now - tolerance
     }
 }
 
 private extension String {
-    func base64URLDecode() -> Data? {
+    func base64Decode() -> Data? {
         var base64 = self
         base64 = base64.replacingOccurrences(of: "-", with: "+")
         base64 = base64.replacingOccurrences(of: "_", with: "/")
diff --git a/Tests/LiveKitTests/ConnectionCredentialsTests.swift b/Tests/LiveKitTests/ConnectionCredentialsTests.swift
new file mode 100644
index 000000000..cadf39ee6
--- /dev/null
+++ b/Tests/LiveKitTests/ConnectionCredentialsTests.swift
@@ -0,0 +1,267 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Foundation
+@testable import LiveKit
+import XCTest
+
+class ConnectionCredentialsTests: LKTestCase {
+    actor MockValidJWTProvider: CredentialsProvider {
+        let serverUrl = URL(string: "wss://test.livekit.io")!
+        let participantName: String
+        var callCount = 0
+
+        init(participantName: String = "test-participant") {
+            self.participantName = participantName
+        }
+
+        func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
+            callCount += 1
+
+            let tokenGenerator = TokenGenerator(
+                apiKey: "test-api-key",
+                apiSecret: "test-api-secret",
+                identity: request.participantIdentity ?? "test-identity"
+            )
+            tokenGenerator.name = request.participantName ?? participantName
+            tokenGenerator.videoGrant = VideoGrant(room: request.roomName ?? "test-room", roomJoin: true)
+
+            let token = try tokenGenerator.sign()
+
+            return ConnectionCredentials.Response(
+                serverUrl: serverUrl,
+                participantToken: token
+            )
+        }
+    }
+
+    actor MockInvalidJWTProvider: CredentialsProvider {
+        let serverUrl = URL(string: "wss://test.livekit.io")!
+        var callCount = 0
+
+        func fetch(_: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
+            callCount += 1
+
+            return ConnectionCredentials.Response(
+                serverUrl: serverUrl,
+                participantToken: "invalid.jwt.token"
+            )
+        }
+    }
+
+    actor MockExpiredJWTProvider: CredentialsProvider {
+        let serverUrl = URL(string: "wss://test.livekit.io")!
+        var callCount = 0
+
+        func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
+            callCount += 1
+
+            let tokenGenerator = TokenGenerator(
+                apiKey: "test-api-key",
+                apiSecret: "test-api-secret",
+                identity: request.participantIdentity ?? "test-identity",
+                ttl: -60
+            )
+            tokenGenerator.name = request.participantName ?? "test-participant"
+            tokenGenerator.videoGrant = VideoGrant(room: request.roomName ?? "test-room", roomJoin: true)
+
+            let token = try tokenGenerator.sign()
+
+            return ConnectionCredentials.Response(
+                serverUrl: serverUrl,
+                participantToken: token
+            )
+        }
+    }
+
+    func testValidJWTCaching() async throws {
+        let mockProvider = MockValidJWTProvider(participantName: "alice")
+        let cachingProvider = CachingCredentialsProvider(mockProvider)
+
+        let request = ConnectionCredentials.Request(
+            roomName: "test-room",
+            participantName: "alice",
+            participantIdentity: "alice-id"
+        )
+
+        let response1 = try await cachingProvider.fetch(request)
+        let callCount1 = await mockProvider.callCount
+        XCTAssertEqual(callCount1, 1)
+        XCTAssertEqual(response1.serverUrl.absoluteString, "wss://test.livekit.io")
+        XCTAssertTrue(response1.hasValidToken(), "Generated token should be valid")
+
+        let response2 = try await cachingProvider.fetch(request)
+        let callCount2 = await mockProvider.callCount
+        XCTAssertEqual(callCount2, 1)
+        XCTAssertEqual(response2.participantToken, response1.participantToken)
+        XCTAssertEqual(response2.serverUrl, response1.serverUrl)
+
+        let differentRequest = ConnectionCredentials.Request(
+            roomName: "different-room",
+            participantName: "alice",
+            participantIdentity: "alice-id"
+        )
+        let response3 = try await cachingProvider.fetch(differentRequest)
+        let callCount3 = await mockProvider.callCount
+        XCTAssertEqual(callCount3, 2)
+        XCTAssertNotEqual(response3.participantToken, response1.participantToken)
+
+        await cachingProvider.invalidate()
+        _ = try await cachingProvider.fetch(request)
+        let callCount4 = await mockProvider.callCount
+        XCTAssertEqual(callCount4, 3)
+    }
+
+    func testInvalidJWTHandling() async throws {
+        let mockInvalidProvider = MockInvalidJWTProvider()
+        let cachingProvider = CachingCredentialsProvider(mockInvalidProvider)
+
+        let request = ConnectionCredentials.Request(
+            roomName: "test-room",
+            participantName: "bob",
+            participantIdentity: "bob-id"
+        )
+
+        let response1 = try await cachingProvider.fetch(request)
+        let callCount1 = await mockInvalidProvider.callCount
+        XCTAssertEqual(callCount1, 1)
+        XCTAssertFalse(response1.hasValidToken(), "Invalid token should not be considered valid")
+
+        let response2 = try await cachingProvider.fetch(request)
+        let callCount2 = await mockInvalidProvider.callCount
+        XCTAssertEqual(callCount2, 2)
+        XCTAssertEqual(response2.participantToken, response1.participantToken)
+
+        let mockExpiredProvider = MockExpiredJWTProvider()
+        let cachingProviderExpired = CachingCredentialsProvider(mockExpiredProvider)
+
+        let response3 = try await cachingProviderExpired.fetch(request)
+        let expiredCallCount1 = await mockExpiredProvider.callCount
+        XCTAssertEqual(expiredCallCount1, 1)
+        XCTAssertFalse(response3.hasValidToken(), "Expired token should not be considered valid")
+
+        _ = try await cachingProviderExpired.fetch(request)
+        let expiredCallCount2 = await mockExpiredProvider.callCount
+        XCTAssertEqual(expiredCallCount2, 2)
+    }
+
+    func testCustomValidator() async throws {
+        let mockProvider = MockValidJWTProvider(participantName: "charlie")
+
+        let customValidator: CachingCredentialsProvider.Validator = { request, response in
+            request.participantName == "charlie" && response.hasValidToken()
+        }
+
+        let cachingProvider = CachingCredentialsProvider(mockProvider, validator: customValidator)
+
+        let charlieRequest = ConnectionCredentials.Request(
+            roomName: "test-room",
+            participantName: "charlie",
+            participantIdentity: "charlie-id"
+        )
+
+        let response1 = try await cachingProvider.fetch(charlieRequest)
+        let callCount1 = await mockProvider.callCount
+        XCTAssertEqual(callCount1, 1)
+        XCTAssertTrue(response1.hasValidToken())
+
+        let response2 = try await cachingProvider.fetch(charlieRequest)
+        let callCount2 = await mockProvider.callCount
+        XCTAssertEqual(callCount2, 1)
+        XCTAssertEqual(response2.participantToken, response1.participantToken)
+
+        let aliceRequest = ConnectionCredentials.Request(
+            roomName: "test-room",
+            participantName: "alice",
+            participantIdentity: "alice-id"
+        )
+
+        _ = try await cachingProvider.fetch(aliceRequest)
+        let callCount3 = await mockProvider.callCount
+        XCTAssertEqual(callCount3, 2)
+
+        _ = try await cachingProvider.fetch(aliceRequest)
+        let callCount4 = await mockProvider.callCount
+        XCTAssertEqual(callCount4, 3)
+
+        let tokenMockProvider = MockValidJWTProvider(participantName: "dave")
+        let tokenContentValidator: CachingCredentialsProvider.Validator = { request, response in
+            request.roomName == "test-room" && response.hasValidToken()
+        }
+
+        let tokenCachingProvider = CachingCredentialsProvider(tokenMockProvider, validator: tokenContentValidator)
+
+        let roomRequest = ConnectionCredentials.Request(
+            roomName: "test-room",
+            participantName: "dave",
+            participantIdentity: "dave-id"
+        )
+
+        _ = try await tokenCachingProvider.fetch(roomRequest)
+        let tokenCallCount1 = await tokenMockProvider.callCount
+        XCTAssertEqual(tokenCallCount1, 1)
+
+        _ = try await tokenCachingProvider.fetch(roomRequest)
+        let tokenCallCount2 = await tokenMockProvider.callCount
+        XCTAssertEqual(tokenCallCount2, 1)
+
+        let differentRoomRequest = ConnectionCredentials.Request(
+            roomName: "different-room",
+            participantName: "dave",
+            participantIdentity: "dave-id"
+        )
+
+        _ = try await tokenCachingProvider.fetch(differentRoomRequest)
+        let tokenCallCount3 = await tokenMockProvider.callCount
+        XCTAssertEqual(tokenCallCount3, 2)
+
+        _ = try await tokenCachingProvider.fetch(differentRoomRequest)
+        let tokenCallCount4 = await tokenMockProvider.callCount
+        XCTAssertEqual(tokenCallCount4, 3)
+    }
+
+    func testConcurrentAccess() async throws {
+        let mockProvider = MockValidJWTProvider(participantName: "concurrent-test")
+        let cachingProvider = CachingCredentialsProvider(mockProvider)
+
+        let request = ConnectionCredentials.Request(
+            roomName: "concurrent-room",
+            participantName: "concurrent-user",
+            participantIdentity: "concurrent-id"
+        )
+
+        let initialResponse = try await cachingProvider.fetch(request)
+        let initialCallCount = await mockProvider.callCount
+        XCTAssertEqual(initialCallCount, 1)
+
+        async let fetch1 = cachingProvider.fetch(request)
+        async let fetch2 = cachingProvider.fetch(request)
+        async let fetch3 = cachingProvider.fetch(request)
+
+        let responses = try await [fetch1, fetch2, fetch3]
+
+        XCTAssertEqual(responses[0].participantToken, initialResponse.participantToken)
+        XCTAssertEqual(responses[1].participantToken, initialResponse.participantToken)
+        XCTAssertEqual(responses[2].participantToken, initialResponse.participantToken)
+
+        XCTAssertEqual(responses[0].serverUrl, initialResponse.serverUrl)
+        XCTAssertEqual(responses[1].serverUrl, initialResponse.serverUrl)
+        XCTAssertEqual(responses[2].serverUrl, initialResponse.serverUrl)
+
+        let finalCallCount = await mockProvider.callCount
+        XCTAssertEqual(finalCallCount, 1)
+    }
+}

From ac4f130262227cd7bbaf32c3a0e54fd8c5a1a1f8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Tue, 16 Sep 2025 13:41:55 +0200
Subject: [PATCH 06/28] Cmts

---
 .../LiveKit/Auth/ConnectionCredentials.swift  | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/Sources/LiveKit/Auth/ConnectionCredentials.swift b/Sources/LiveKit/Auth/ConnectionCredentials.swift
index 62df4703a..00566fbeb 100644
--- a/Sources/LiveKit/Auth/ConnectionCredentials.swift
+++ b/Sources/LiveKit/Auth/ConnectionCredentials.swift
@@ -16,13 +16,23 @@
 
 import Foundation
 
+/// `ConnectionCredentials` represent the credentials needed for connecting to a new Room.
+/// - SeeAlso: [LiveKit's Authentication Documentation](https://docs.livekit.io/home/get-started/authentication/) for more information.
 public enum ConnectionCredentials {
+    /// Request parameters for generating connection credentials.
     public struct Request: Encodable, Sendable, Equatable {
+        /// The name of the room being requested when generating credentials.
         let roomName: String?
+        /// The name of the participant being requested for this client when generating credentials.
         let participantName: String?
+        /// The identity of the participant being requested for this client when generating credentials.
         let participantIdentity: String?
+        /// Any participant metadata being included along with the credentials generation operation.
         let participantMetadata: String?
+        /// Any participant attributes being included along with the credentials generation operation.
         let participantAttributes: [String: String]?
+        /// A `RoomConfiguration` object can be passed to request extra parameters should be included when generating connection credentials - dispatching agents, etc.
+        /// - SeeAlso: [Room Configuration Documentation](https://docs.livekit.io/home/get-started/authentication/#room-configuration) for more info.
         let roomConfiguration: RoomConfiguration?
 
         public init(
@@ -42,8 +52,11 @@ public enum ConnectionCredentials {
         }
     }
 
+    /// Response containing the credentials needed to connect to a room.
     public struct Response: Decodable, Sendable {
+        /// The WebSocket URL for the LiveKit server.
         let serverUrl: URL
+        /// The JWT token containing participant permissions and metadata.
         let participantToken: String
 
         public init(serverUrl: URL, participantToken: String) {
@@ -58,10 +71,14 @@ public enum ConnectionCredentials {
 
 // MARK: - Provider
 
+/// Protocol for types that can provide connection credentials.
+/// Implement this protocol to create custom credential providers (e.g., fetching from your backend API).
 public protocol CredentialsProvider: Sendable {
     func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response
 }
 
+/// `ConnectionCredentials.Literal` contains a single set of credentials, hard-coded or acquired from a static source.
+/// - Note: It does not support refresing credentials.
 extension ConnectionCredentials.Literal: CredentialsProvider {
     public func fetch(_: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
         self
@@ -70,9 +87,15 @@ extension ConnectionCredentials.Literal: CredentialsProvider {
 
 // MARK: - Token Server
 
+/// Protocol for token servers that fetch credentials via HTTP requests.
+/// Provides a default implementation of `fetch` that can be used to integrate with custom backend token generation endpoints.
+/// - Note: The response is expected to be a `ConnectionCredentials.Response` object.
 public protocol TokenServer: CredentialsProvider {
+    /// The URL endpoint for token generation.
     var url: URL { get }
+    /// The HTTP method to use (defaults to "POST").
     var method: String { get }
+    /// Additional HTTP headers to include with the request.
     var headers: [String: String] { get }
 }
 
@@ -103,14 +126,19 @@ public extension TokenServer {
     }
 }
 
+/// `SandboxTokenServer` queries LiveKit Sandbox token server for credentials,
+/// which supports quick prototyping/getting started types of use cases.
+/// - Warning: This token provider is **INSECURE** and should **NOT** be used in production.
 public struct SandboxTokenServer: TokenServer {
     public let url = URL(string: "https://cloud-api.livekit.io/api/sandbox/connection-details")!
     public var headers: [String: String] {
         ["X-Sandbox-ID": id.trimmingCharacters(in: CharacterSet(charactersIn: "\""))]
     }
 
+    /// The sandbox ID provided by LiveKit Cloud.
     public let id: String
 
+    /// Initialize with a sandbox ID from LiveKit Cloud.
     public init(id: String) {
         self.id = id
     }
@@ -118,8 +146,11 @@ public struct SandboxTokenServer: TokenServer {
 
 // MARK: - Cache
 
+/// `CachingCredentialsProvider` handles in-memory caching of credentials from any other `CredentialsProvider`.
 public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
+    /// A tuple containing the request and response that were cached.
     public typealias Cached = (ConnectionCredentials.Request, ConnectionCredentials.Response)
+    /// A closure that validates whether cached credentials are still valid.
     public typealias Validator = (ConnectionCredentials.Request, ConnectionCredentials.Response) -> Bool
 
     private let provider: CredentialsProvider
@@ -127,6 +158,10 @@ public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
 
     private var cached: Cached?
 
+    /// Initialize a caching wrapper around any credentials provider.
+    /// - Parameters:
+    ///   - provider: The underlying credentials provider to wrap
+    ///   - validator: A closure to determine if cached credentials are still valid (defaults to JWT expiration check)
     public init(_ provider: CredentialsProvider, validator: @escaping Validator = { _, res in res.hasValidToken() }) {
         self.provider = provider
         self.validator = validator
@@ -143,6 +178,7 @@ public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
         return response
     }
 
+    /// Invalidate the cached credentials, forcing a fresh fetch on the next request.
     public func invalidate() {
         cached = nil
     }

From 8660c25155f412a27f12a68a18cda61b29da1ee9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Tue, 16 Sep 2025 13:54:51 +0200
Subject: [PATCH 07/28] Extract storage

---
 .../LiveKit/Auth/ConnectionCredentials.swift  | 57 ++++++++++++++++---
 1 file changed, 50 insertions(+), 7 deletions(-)

diff --git a/Sources/LiveKit/Auth/ConnectionCredentials.swift b/Sources/LiveKit/Auth/ConnectionCredentials.swift
index 00566fbeb..083373a9f 100644
--- a/Sources/LiveKit/Auth/ConnectionCredentials.swift
+++ b/Sources/LiveKit/Auth/ConnectionCredentials.swift
@@ -146,7 +146,7 @@ public struct SandboxTokenServer: TokenServer {
 
 // MARK: - Cache
 
-/// `CachingCredentialsProvider` handles in-memory caching of credentials from any other `CredentialsProvider`.
+/// `CachingCredentialsProvider` handles caching of credentials from any other `CredentialsProvider` using configurable storage.
 public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
     /// A tuple containing the request and response that were cached.
     public typealias Cached = (ConnectionCredentials.Request, ConnectionCredentials.Response)
@@ -155,31 +155,74 @@ public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
 
     private let provider: CredentialsProvider
     private let validator: Validator
-
-    private var cached: Cached?
+    private let storage: CredentialsStorage
 
     /// Initialize a caching wrapper around any credentials provider.
     /// - Parameters:
     ///   - provider: The underlying credentials provider to wrap
+    ///   - storage: The storage implementation to use for caching (defaults to in-memory storage)
     ///   - validator: A closure to determine if cached credentials are still valid (defaults to JWT expiration check)
-    public init(_ provider: CredentialsProvider, validator: @escaping Validator = { _, res in res.hasValidToken() }) {
+    public init(
+        _ provider: CredentialsProvider,
+        storage: CredentialsStorage = InMemoryCredentialsStorage(),
+        validator: @escaping Validator = { _, res in res.hasValidToken() }
+    ) {
         self.provider = provider
+        self.storage = storage
         self.validator = validator
     }
 
     public func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
-        if let (cachedRequest, cachedResponse) = cached, cachedRequest == request, validator(cachedRequest, cachedResponse) {
+        if let (cachedRequest, cachedResponse) = await storage.retrieve(),
+           cachedRequest == request,
+           validator(cachedRequest, cachedResponse)
+        {
             log("Using cached credentials", .debug)
             return cachedResponse
         }
 
         let response = try await provider.fetch(request)
-        cached = (request, response)
+        try await storage.store((request, response))
         return response
     }
 
     /// Invalidate the cached credentials, forcing a fresh fetch on the next request.
-    public func invalidate() {
+    public func invalidate() async {
+        await storage.clear()
+    }
+}
+
+// MARK: - Storage
+
+/// Protocol for abstract storage that can persist and retrieve a single cached credential pair.
+/// Implement this protocol to create custom storage implementations e.g. for Keychain.
+public protocol CredentialsStorage: Sendable {
+    /// Store credentials in the storage (replaces any existing credentials)
+    func store(_ credentials: CachingCredentialsProvider.Cached) async throws
+
+    /// Retrieve the cached credentials
+    /// - Returns: The cached credentials if found, nil otherwise
+    func retrieve() async -> CachingCredentialsProvider.Cached?
+
+    /// Clear the stored credentials
+    func clear() async
+}
+
+/// Simple in-memory storage implementation
+public actor InMemoryCredentialsStorage: CredentialsStorage {
+    private var cached: CachingCredentialsProvider.Cached?
+
+    public init() {}
+
+    public func store(_ credentials: CachingCredentialsProvider.Cached) async throws {
+        cached = credentials
+    }
+
+    public func retrieve() async -> CachingCredentialsProvider.Cached? {
+        cached
+    }
+
+    public func clear() async {
         cached = nil
     }
 }

From f67c892c8eba5200843a4e48403f8c3194c45c0a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Tue, 16 Sep 2025 13:56:40 +0200
Subject: [PATCH 08/28] Change

---
 .changes/connection-credentials | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 .changes/connection-credentials

diff --git a/.changes/connection-credentials b/.changes/connection-credentials
new file mode 100644
index 000000000..d60db7942
--- /dev/null
+++ b/.changes/connection-credentials
@@ -0,0 +1 @@
+patch type="added" "Abstract credential providers for easier token fetching"

From 709949fb90bc7c2a3b84a8d9054c3bbb24b24f08 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Wed, 17 Sep 2025 09:32:29 +0200
Subject: [PATCH 09/28] Expose cached, naming

---
 .../LiveKit/Auth/ConnectionCredentials.swift  | 46 +++++++++++--------
 1 file changed, 27 insertions(+), 19 deletions(-)

diff --git a/Sources/LiveKit/Auth/ConnectionCredentials.swift b/Sources/LiveKit/Auth/ConnectionCredentials.swift
index 083373a9f..98f2f240b 100644
--- a/Sources/LiveKit/Auth/ConnectionCredentials.swift
+++ b/Sources/LiveKit/Auth/ConnectionCredentials.swift
@@ -16,6 +16,8 @@
 
 import Foundation
 
+#warning("Fix camel case after deploying backend")
+
 /// `ConnectionCredentials` represent the credentials needed for connecting to a new Room.
 /// - SeeAlso: [LiveKit's Authentication Documentation](https://docs.livekit.io/home/get-started/authentication/) for more information.
 public enum ConnectionCredentials {
@@ -132,7 +134,7 @@ public extension TokenServer {
 public struct SandboxTokenServer: TokenServer {
     public let url = URL(string: "https://cloud-api.livekit.io/api/sandbox/connection-details")!
     public var headers: [String: String] {
-        ["X-Sandbox-ID": id.trimmingCharacters(in: CharacterSet(charactersIn: "\""))]
+        ["X-Sandbox-ID": id]
     }
 
     /// The sandbox ID provided by LiveKit Cloud.
@@ -140,13 +142,13 @@ public struct SandboxTokenServer: TokenServer {
 
     /// Initialize with a sandbox ID from LiveKit Cloud.
     public init(id: String) {
-        self.id = id
+        self.id = id.trimmingCharacters(in: CharacterSet(charactersIn: "\""))
     }
 }
 
 // MARK: - Cache
 
-/// `CachingCredentialsProvider` handles caching of credentials from any other `CredentialsProvider` using configurable storage.
+/// `CachingCredentialsProvider` handles caching of credentials from any other `CredentialsProvider` using configurable store.
 public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
     /// A tuple containing the request and response that were cached.
     public typealias Cached = (ConnectionCredentials.Request, ConnectionCredentials.Response)
@@ -155,25 +157,25 @@ public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
 
     private let provider: CredentialsProvider
     private let validator: Validator
-    private let storage: CredentialsStorage
+    private let store: CredentialsStore
 
     /// Initialize a caching wrapper around any credentials provider.
     /// - Parameters:
     ///   - provider: The underlying credentials provider to wrap
-    ///   - storage: The storage implementation to use for caching (defaults to in-memory storage)
+    ///   - store: The store implementation to use for caching (defaults to in-memory store)
     ///   - validator: A closure to determine if cached credentials are still valid (defaults to JWT expiration check)
     public init(
         _ provider: CredentialsProvider,
-        storage: CredentialsStorage = InMemoryCredentialsStorage(),
+        store: CredentialsStore = InMemoryCredentialsStore(),
         validator: @escaping Validator = { _, res in res.hasValidToken() }
     ) {
         self.provider = provider
-        self.storage = storage
+        self.store = store
         self.validator = validator
     }
 
     public func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
-        if let (cachedRequest, cachedResponse) = await storage.retrieve(),
+        if let (cachedRequest, cachedResponse) = await store.retrieve(),
            cachedRequest == request,
            validator(cachedRequest, cachedResponse)
         {
@@ -182,23 +184,29 @@ public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
         }
 
         let response = try await provider.fetch(request)
-        try await storage.store((request, response))
+        await store.store((request, response))
         return response
     }
 
     /// Invalidate the cached credentials, forcing a fresh fetch on the next request.
     public func invalidate() async {
-        await storage.clear()
+        await store.clear()
+    }
+
+    /// Get the cached credentials
+    /// - Returns: The cached credentials if found, nil otherwise
+    public func getCachedCredentials() async -> CachingCredentialsProvider.Cached? {
+        await store.retrieve()
     }
 }
 
-// MARK: - Storage
+// MARK: - Store
 
-/// Protocol for abstract storage that can persist and retrieve a single cached credential pair.
-/// Implement this protocol to create custom storage implementations e.g. for Keychain.
-public protocol CredentialsStorage: Sendable {
-    /// Store credentials in the storage (replaces any existing credentials)
-    func store(_ credentials: CachingCredentialsProvider.Cached) async throws
+/// Protocol for abstract store that can persist and retrieve a single cached credential pair.
+/// Implement this protocol to create custom store implementations e.g. for Keychain.
+public protocol CredentialsStore: Sendable {
+    /// Store credentials in the store (replaces any existing credentials)
+    func store(_ credentials: CachingCredentialsProvider.Cached) async
 
     /// Retrieve the cached credentials
     /// - Returns: The cached credentials if found, nil otherwise
@@ -208,13 +216,13 @@ public protocol CredentialsStorage: Sendable {
     func clear() async
 }
 
-/// Simple in-memory storage implementation
-public actor InMemoryCredentialsStorage: CredentialsStorage {
+/// Simple in-memory store implementation
+public actor InMemoryCredentialsStore: CredentialsStore {
     private var cached: CachingCredentialsProvider.Cached?
 
     public init() {}
 
-    public func store(_ credentials: CachingCredentialsProvider.Cached) async throws {
+    public func store(_ credentials: CachingCredentialsProvider.Cached) async {
         cached = credentials
     }
 

From 9c792fd456f9561a24fc6be80a9e11331471e242 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Wed, 17 Sep 2025 09:38:01 +0200
Subject: [PATCH 10/28] JSON keys

---
 .../LiveKit/Auth/ConnectionCredentials.swift  | 24 +++++++++++++++----
 Sources/LiveKit/Core/Room.swift               |  2 +-
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/Sources/LiveKit/Auth/ConnectionCredentials.swift b/Sources/LiveKit/Auth/ConnectionCredentials.swift
index 98f2f240b..5859cdb12 100644
--- a/Sources/LiveKit/Auth/ConnectionCredentials.swift
+++ b/Sources/LiveKit/Auth/ConnectionCredentials.swift
@@ -37,6 +37,15 @@ public enum ConnectionCredentials {
         /// - SeeAlso: [Room Configuration Documentation](https://docs.livekit.io/home/get-started/authentication/#room-configuration) for more info.
         let roomConfiguration: RoomConfiguration?
 
+        // enum CodingKeys: String, CodingKey {
+        //     case roomName = "room_name"
+        //     case participantName = "participant_name"
+        //     case participantIdentity = "participant_identity"
+        //     case participantMetadata = "participant_metadata"
+        //     case participantAttributes = "participant_attributes"
+        //     case roomConfiguration = "room_configuration"
+        // }
+
         public init(
             roomName: String? = nil,
             participantName: String? = nil,
@@ -57,12 +66,17 @@ public enum ConnectionCredentials {
     /// Response containing the credentials needed to connect to a room.
     public struct Response: Decodable, Sendable {
         /// The WebSocket URL for the LiveKit server.
-        let serverUrl: URL
+        let serverURL: URL
         /// The JWT token containing participant permissions and metadata.
         let participantToken: String
 
-        public init(serverUrl: URL, participantToken: String) {
-            self.serverUrl = serverUrl
+        enum CodingKeys: String, CodingKey {
+            case serverURL = "serverUrl"
+            case participantToken
+        }
+
+        public init(serverURL: URL, participantToken: String) {
+            self.serverURL = serverURL
             self.participantToken = participantToken
         }
     }
@@ -117,11 +131,11 @@ public extension TokenServer {
         let (data, response) = try await URLSession.shared.data(for: urlRequest)
 
         guard let httpResponse = response as? HTTPURLResponse else {
-            throw LiveKitError(.network, message: "Error generating token from sandbox token server, no response")
+            throw LiveKitError(.network, message: "Error generating token from the token server, no response")
         }
 
         guard (200 ... 299).contains(httpResponse.statusCode) else {
-            throw LiveKitError(.network, message: "Error generating token from sandbox token server, received \(httpResponse)")
+            throw LiveKitError(.network, message: "Error generating token from the token server, received \(httpResponse)")
         }
 
         return try JSONDecoder().decode(ConnectionCredentials.Response.self, from: data)
diff --git a/Sources/LiveKit/Core/Room.swift b/Sources/LiveKit/Core/Room.swift
index eeceb2f9e..04d5afae3 100644
--- a/Sources/LiveKit/Core/Room.swift
+++ b/Sources/LiveKit/Core/Room.swift
@@ -414,7 +414,7 @@ public class Room: NSObject, @unchecked Sendable, ObservableObject, Loggable {
                         roomOptions: RoomOptions? = nil) async throws
     {
         let credentials = try await credentialsProvider.fetch(credentialsOptions)
-        try await connect(url: credentials.serverUrl.absoluteString, token: credentials.participantToken, connectOptions: connectOptions, roomOptions: roomOptions)
+        try await connect(url: credentials.serverURL.absoluteString, token: credentials.participantToken, connectOptions: connectOptions, roomOptions: roomOptions)
     }
 
     @objc

From 84a6093cbd1e4a1cb1c8bd2f5146ff4a14d11afe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Wed, 17 Sep 2025 10:32:38 +0200
Subject: [PATCH 11/28] Cache provider

---
 Sources/LiveKit/Core/Room.swift | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Sources/LiveKit/Core/Room.swift b/Sources/LiveKit/Core/Room.swift
index 04d5afae3..0c3760d70 100644
--- a/Sources/LiveKit/Core/Room.swift
+++ b/Sources/LiveKit/Core/Room.swift
@@ -82,6 +82,9 @@ public class Room: NSObject, @unchecked Sendable, ObservableObject, Loggable {
     @objc
     public var publishersCount: Int { _state.numPublishers }
 
+    // Credentials
+    public var credentialsProvider: (any CredentialsProvider)?
+
     // expose engine's vars
     @objc
     public var url: String? { _state.url?.absoluteString }
@@ -415,6 +418,7 @@ public class Room: NSObject, @unchecked Sendable, ObservableObject, Loggable {
     {
         let credentials = try await credentialsProvider.fetch(credentialsOptions)
         try await connect(url: credentials.serverURL.absoluteString, token: credentials.participantToken, connectOptions: connectOptions, roomOptions: roomOptions)
+        self.credentialsProvider = credentialsProvider
     }
 
     @objc

From de51dfac2eb0581b22b0a3e02cdfef2dac86cf3b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Wed, 17 Sep 2025 11:29:59 +0200
Subject: [PATCH 12/28] Log

---
 Sources/LiveKit/Auth/ConnectionCredentials.swift | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Sources/LiveKit/Auth/ConnectionCredentials.swift b/Sources/LiveKit/Auth/ConnectionCredentials.swift
index 5859cdb12..97149ba69 100644
--- a/Sources/LiveKit/Auth/ConnectionCredentials.swift
+++ b/Sources/LiveKit/Auth/ConnectionCredentials.swift
@@ -134,7 +134,7 @@ public extension TokenServer {
             throw LiveKitError(.network, message: "Error generating token from the token server, no response")
         }
 
-        guard (200 ... 299).contains(httpResponse.statusCode) else {
+        guard (200 ..< 300).contains(httpResponse.statusCode) else {
             throw LiveKitError(.network, message: "Error generating token from the token server, received \(httpResponse)")
         }
 
@@ -170,8 +170,8 @@ public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
     public typealias Validator = (ConnectionCredentials.Request, ConnectionCredentials.Response) -> Bool
 
     private let provider: CredentialsProvider
-    private let validator: Validator
     private let store: CredentialsStore
+    private let validator: Validator
 
     /// Initialize a caching wrapper around any credentials provider.
     /// - Parameters:
@@ -197,6 +197,7 @@ public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
             return cachedResponse
         }
 
+        log("Requesting new credentials", .debug)
         let response = try await provider.fetch(request)
         await store.store((request, response))
         return response

From 966536a1e0f74424876ea39d94ba13a8913d79eb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Fri, 19 Sep 2025 08:59:50 +0200
Subject: [PATCH 13/28] Renaming

---
 ...ionCredentials.swift => TokenSource.swift} | 78 +++++++++----------
 Sources/LiveKit/Core/Room.swift               | 13 ++--
 2 files changed, 46 insertions(+), 45 deletions(-)
 rename Sources/LiveKit/Auth/{ConnectionCredentials.swift => TokenSource.swift} (76%)

diff --git a/Sources/LiveKit/Auth/ConnectionCredentials.swift b/Sources/LiveKit/Auth/TokenSource.swift
similarity index 76%
rename from Sources/LiveKit/Auth/ConnectionCredentials.swift
rename to Sources/LiveKit/Auth/TokenSource.swift
index 97149ba69..39fa0429a 100644
--- a/Sources/LiveKit/Auth/ConnectionCredentials.swift
+++ b/Sources/LiveKit/Auth/TokenSource.swift
@@ -18,9 +18,9 @@ import Foundation
 
 #warning("Fix camel case after deploying backend")
 
-/// `ConnectionCredentials` represent the credentials needed for connecting to a new Room.
+/// `Token` represent the credentials needed for connecting to a new Room.
 /// - SeeAlso: [LiveKit's Authentication Documentation](https://docs.livekit.io/home/get-started/authentication/) for more information.
-public enum ConnectionCredentials {
+public enum Token {
     /// Request parameters for generating connection credentials.
     public struct Request: Encodable, Sendable, Equatable {
         /// The name of the room being requested when generating credentials.
@@ -89,14 +89,14 @@ public enum ConnectionCredentials {
 
 /// Protocol for types that can provide connection credentials.
 /// Implement this protocol to create custom credential providers (e.g., fetching from your backend API).
-public protocol CredentialsProvider: Sendable {
-    func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response
+public protocol TokenSource: Sendable {
+    func fetch(_ request: Token.Request) async throws -> Token.Response
 }
 
-/// `ConnectionCredentials.Literal` contains a single set of credentials, hard-coded or acquired from a static source.
-/// - Note: It does not support refresing credentials.
-extension ConnectionCredentials.Literal: CredentialsProvider {
-    public func fetch(_: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
+/// `Token.Literal` contains a single set of credentials, hard-coded or acquired from a static source.
+/// - Note: It does not support refreshing credentials.
+extension Token.Literal: TokenSource {
+    public func fetch(_: Token.Request) async throws -> Token.Response {
         self
     }
 }
@@ -105,8 +105,8 @@ extension ConnectionCredentials.Literal: CredentialsProvider {
 
 /// Protocol for token servers that fetch credentials via HTTP requests.
 /// Provides a default implementation of `fetch` that can be used to integrate with custom backend token generation endpoints.
-/// - Note: The response is expected to be a `ConnectionCredentials.Response` object.
-public protocol TokenServer: CredentialsProvider {
+/// - Note: The response is expected to be a `Token.Response` object.
+public protocol TokenEndpoint: TokenSource {
     /// The URL endpoint for token generation.
     var url: URL { get }
     /// The HTTP method to use (defaults to "POST").
@@ -115,11 +115,11 @@ public protocol TokenServer: CredentialsProvider {
     var headers: [String: String] { get }
 }
 
-public extension TokenServer {
+public extension TokenEndpoint {
     var method: String { "POST" }
     var headers: [String: String] { [:] }
 
-    func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
+    func fetch(_ request: Token.Request) async throws -> Token.Response {
         var urlRequest = URLRequest(url: url)
 
         urlRequest.httpMethod = method
@@ -138,14 +138,14 @@ public extension TokenServer {
             throw LiveKitError(.network, message: "Error generating token from the token server, received \(httpResponse)")
         }
 
-        return try JSONDecoder().decode(ConnectionCredentials.Response.self, from: data)
+        return try JSONDecoder().decode(Token.Response.self, from: data)
     }
 }
 
-/// `SandboxTokenServer` queries LiveKit Sandbox token server for credentials,
+/// `Sandbox` queries LiveKit Sandbox token server for credentials,
 /// which supports quick prototyping/getting started types of use cases.
-/// - Warning: This token provider is **INSECURE** and should **NOT** be used in production.
-public struct SandboxTokenServer: TokenServer {
+/// - Warning: This token endpoint is **INSECURE** and should **NOT** be used in production.
+public struct Sandbox: TokenEndpoint {
     public let url = URL(string: "https://cloud-api.livekit.io/api/sandbox/connection-details")!
     public var headers: [String: String] {
         ["X-Sandbox-ID": id]
@@ -162,33 +162,33 @@ public struct SandboxTokenServer: TokenServer {
 
 // MARK: - Cache
 
-/// `CachingCredentialsProvider` handles caching of credentials from any other `CredentialsProvider` using configurable store.
-public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
+/// `CachingTokenSource` handles caching of credentials from any other `TokenSource` using configurable store.
+public actor CachingTokenSource: TokenSource, Loggable {
     /// A tuple containing the request and response that were cached.
-    public typealias Cached = (ConnectionCredentials.Request, ConnectionCredentials.Response)
+    public typealias Cached = (Token.Request, Token.Response)
     /// A closure that validates whether cached credentials are still valid.
-    public typealias Validator = (ConnectionCredentials.Request, ConnectionCredentials.Response) -> Bool
+    public typealias TokenValidator = (Token.Request, Token.Response) -> Bool
 
-    private let provider: CredentialsProvider
-    private let store: CredentialsStore
-    private let validator: Validator
+    private let source: TokenSource
+    private let store: TokenStore
+    private let validator: TokenValidator
 
     /// Initialize a caching wrapper around any credentials provider.
     /// - Parameters:
-    ///   - provider: The underlying credentials provider to wrap
+    ///   - source: The underlying token source to wrap
     ///   - store: The store implementation to use for caching (defaults to in-memory store)
     ///   - validator: A closure to determine if cached credentials are still valid (defaults to JWT expiration check)
     public init(
-        _ provider: CredentialsProvider,
-        store: CredentialsStore = InMemoryCredentialsStore(),
-        validator: @escaping Validator = { _, res in res.hasValidToken() }
+        _ source: TokenSource,
+        store: TokenStore = InMemoryTokenStore(),
+        validator: @escaping TokenValidator = { _, res in res.hasValidToken() }
     ) {
-        self.provider = provider
+        self.source = source
         self.store = store
         self.validator = validator
     }
 
-    public func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
+    public func fetch(_ request: Token.Request) async throws -> Token.Response {
         if let (cachedRequest, cachedResponse) = await store.retrieve(),
            cachedRequest == request,
            validator(cachedRequest, cachedResponse)
@@ -198,7 +198,7 @@ public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
         }
 
         log("Requesting new credentials", .debug)
-        let response = try await provider.fetch(request)
+        let response = try await source.fetch(request)
         await store.store((request, response))
         return response
     }
@@ -210,7 +210,7 @@ public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
 
     /// Get the cached credentials
     /// - Returns: The cached credentials if found, nil otherwise
-    public func getCachedCredentials() async -> CachingCredentialsProvider.Cached? {
+    public func getCachedCredentials() async -> CachingTokenSource.Cached? {
         await store.retrieve()
     }
 }
@@ -219,29 +219,29 @@ public actor CachingCredentialsProvider: CredentialsProvider, Loggable {
 
 /// Protocol for abstract store that can persist and retrieve a single cached credential pair.
 /// Implement this protocol to create custom store implementations e.g. for Keychain.
-public protocol CredentialsStore: Sendable {
+public protocol TokenStore: Sendable {
     /// Store credentials in the store (replaces any existing credentials)
-    func store(_ credentials: CachingCredentialsProvider.Cached) async
+    func store(_ credentials: CachingTokenSource.Cached) async
 
     /// Retrieve the cached credentials
     /// - Returns: The cached credentials if found, nil otherwise
-    func retrieve() async -> CachingCredentialsProvider.Cached?
+    func retrieve() async -> CachingTokenSource.Cached?
 
     /// Clear the stored credentials
     func clear() async
 }
 
 /// Simple in-memory store implementation
-public actor InMemoryCredentialsStore: CredentialsStore {
-    private var cached: CachingCredentialsProvider.Cached?
+public actor InMemoryTokenStore: TokenStore {
+    private var cached: CachingTokenSource.Cached?
 
     public init() {}
 
-    public func store(_ credentials: CachingCredentialsProvider.Cached) async {
+    public func store(_ credentials: CachingTokenSource.Cached) async {
         cached = credentials
     }
 
-    public func retrieve() async -> CachingCredentialsProvider.Cached? {
+    public func retrieve() async -> CachingTokenSource.Cached? {
         cached
     }
 
@@ -252,7 +252,7 @@ public actor InMemoryCredentialsStore: CredentialsStore {
 
 // MARK: - Validation
 
-public extension ConnectionCredentials.Response {
+public extension Token.Response {
     func hasValidToken(withTolerance tolerance: TimeInterval = 60) -> Bool {
         let parts = participantToken.components(separatedBy: ".")
         guard parts.count == 3 else {
diff --git a/Sources/LiveKit/Core/Room.swift b/Sources/LiveKit/Core/Room.swift
index 0c3760d70..95379ff52 100644
--- a/Sources/LiveKit/Core/Room.swift
+++ b/Sources/LiveKit/Core/Room.swift
@@ -83,7 +83,7 @@ public class Room: NSObject, @unchecked Sendable, ObservableObject, Loggable {
     public var publishersCount: Int { _state.numPublishers }
 
     // Credentials
-    public var credentialsProvider: (any CredentialsProvider)?
+    public var tokenSource: (any TokenSource)?
 
     // expose engine's vars
     @objc
@@ -411,14 +411,15 @@ public class Room: NSObject, @unchecked Sendable, ObservableObject, Loggable {
         log("Connected to \(String(describing: self))", .info)
     }
 
-    public func connect(credentialsProvider: CredentialsProvider,
-                        credentialsOptions: ConnectionCredentials.Options = .init(),
+    public func connect(tokenSource: TokenSource,
+                        tokenOptions: Token.Options = .init(),
                         connectOptions: ConnectOptions? = nil,
                         roomOptions: RoomOptions? = nil) async throws
     {
-        let credentials = try await credentialsProvider.fetch(credentialsOptions)
-        try await connect(url: credentials.serverURL.absoluteString, token: credentials.participantToken, connectOptions: connectOptions, roomOptions: roomOptions)
-        self.credentialsProvider = credentialsProvider
+        self.tokenSource = tokenSource
+
+        let token = try await tokenSource.fetch(tokenOptions)
+        try await connect(url: token.serverURL.absoluteString, token: token.participantToken, connectOptions: connectOptions, roomOptions: roomOptions)
     }
 
     @objc

From eca4317ed1e6a2e17d4dac33df7a5bd7f4953dd0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Fri, 19 Sep 2025 09:08:36 +0200
Subject: [PATCH 14/28] Fix tests

---
 .../TokenSourceTests.swift}                   | 164 +++++++++---------
 1 file changed, 82 insertions(+), 82 deletions(-)
 rename Tests/LiveKitTests/{ConnectionCredentialsTests.swift => Auth/TokenSourceTests.swift} (50%)

diff --git a/Tests/LiveKitTests/ConnectionCredentialsTests.swift b/Tests/LiveKitTests/Auth/TokenSourceTests.swift
similarity index 50%
rename from Tests/LiveKitTests/ConnectionCredentialsTests.swift
rename to Tests/LiveKitTests/Auth/TokenSourceTests.swift
index cadf39ee6..db51079ec 100644
--- a/Tests/LiveKitTests/ConnectionCredentialsTests.swift
+++ b/Tests/LiveKitTests/Auth/TokenSourceTests.swift
@@ -18,9 +18,9 @@ import Foundation
 @testable import LiveKit
 import XCTest
 
-class ConnectionCredentialsTests: LKTestCase {
-    actor MockValidJWTProvider: CredentialsProvider {
-        let serverUrl = URL(string: "wss://test.livekit.io")!
+class TokenSourceTests: LKTestCase {
+    actor MockValidJWTSource: TokenSource {
+        let serverURL = URL(string: "wss://test.livekit.io")!
         let participantName: String
         var callCount = 0
 
@@ -28,7 +28,7 @@ class ConnectionCredentialsTests: LKTestCase {
             self.participantName = participantName
         }
 
-        func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
+        func fetch(_ request: Token.Request) async throws -> Token.Response {
             callCount += 1
 
             let tokenGenerator = TokenGenerator(
@@ -41,32 +41,32 @@ class ConnectionCredentialsTests: LKTestCase {
 
             let token = try tokenGenerator.sign()
 
-            return ConnectionCredentials.Response(
-                serverUrl: serverUrl,
+            return Token.Response(
+                serverURL: serverURL,
                 participantToken: token
             )
         }
     }
 
-    actor MockInvalidJWTProvider: CredentialsProvider {
-        let serverUrl = URL(string: "wss://test.livekit.io")!
+    actor MockInvalidJWTSource: TokenSource {
+        let serverURL = URL(string: "wss://test.livekit.io")!
         var callCount = 0
 
-        func fetch(_: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
+        func fetch(_: Token.Request) async throws -> Token.Response {
             callCount += 1
 
-            return ConnectionCredentials.Response(
-                serverUrl: serverUrl,
+            return Token.Response(
+                serverURL: serverURL,
                 participantToken: "invalid.jwt.token"
             )
         }
     }
 
-    actor MockExpiredJWTProvider: CredentialsProvider {
-        let serverUrl = URL(string: "wss://test.livekit.io")!
+    actor MockExpiredJWTSource: TokenSource {
+        let serverURL = URL(string: "wss://test.livekit.io")!
         var callCount = 0
 
-        func fetch(_ request: ConnectionCredentials.Request) async throws -> ConnectionCredentials.Response {
+        func fetch(_ request: Token.Request) async throws -> Token.Response {
             callCount += 1
 
             let tokenGenerator = TokenGenerator(
@@ -80,176 +80,176 @@ class ConnectionCredentialsTests: LKTestCase {
 
             let token = try tokenGenerator.sign()
 
-            return ConnectionCredentials.Response(
-                serverUrl: serverUrl,
+            return Token.Response(
+                serverURL: serverURL,
                 participantToken: token
             )
         }
     }
 
     func testValidJWTCaching() async throws {
-        let mockProvider = MockValidJWTProvider(participantName: "alice")
-        let cachingProvider = CachingCredentialsProvider(mockProvider)
+        let mockSource = MockValidJWTSource(participantName: "alice")
+        let cachingSource = CachingTokenSource(mockSource)
 
-        let request = ConnectionCredentials.Request(
+        let request = Token.Request(
             roomName: "test-room",
             participantName: "alice",
             participantIdentity: "alice-id"
         )
 
-        let response1 = try await cachingProvider.fetch(request)
-        let callCount1 = await mockProvider.callCount
+        let response1 = try await cachingSource.fetch(request)
+        let callCount1 = await mockSource.callCount
         XCTAssertEqual(callCount1, 1)
-        XCTAssertEqual(response1.serverUrl.absoluteString, "wss://test.livekit.io")
+        XCTAssertEqual(response1.serverURL.absoluteString, "wss://test.livekit.io")
         XCTAssertTrue(response1.hasValidToken(), "Generated token should be valid")
 
-        let response2 = try await cachingProvider.fetch(request)
-        let callCount2 = await mockProvider.callCount
+        let response2 = try await cachingSource.fetch(request)
+        let callCount2 = await mockSource.callCount
         XCTAssertEqual(callCount2, 1)
         XCTAssertEqual(response2.participantToken, response1.participantToken)
-        XCTAssertEqual(response2.serverUrl, response1.serverUrl)
+        XCTAssertEqual(response2.serverURL, response1.serverURL)
 
-        let differentRequest = ConnectionCredentials.Request(
+        let differentRequest = Token.Request(
             roomName: "different-room",
             participantName: "alice",
             participantIdentity: "alice-id"
         )
-        let response3 = try await cachingProvider.fetch(differentRequest)
-        let callCount3 = await mockProvider.callCount
+        let response3 = try await cachingSource.fetch(differentRequest)
+        let callCount3 = await mockSource.callCount
         XCTAssertEqual(callCount3, 2)
         XCTAssertNotEqual(response3.participantToken, response1.participantToken)
 
-        await cachingProvider.invalidate()
-        _ = try await cachingProvider.fetch(request)
-        let callCount4 = await mockProvider.callCount
+        await cachingSource.invalidate()
+        _ = try await cachingSource.fetch(request)
+        let callCount4 = await mockSource.callCount
         XCTAssertEqual(callCount4, 3)
     }
 
     func testInvalidJWTHandling() async throws {
-        let mockInvalidProvider = MockInvalidJWTProvider()
-        let cachingProvider = CachingCredentialsProvider(mockInvalidProvider)
+        let mockInvalidSource = MockInvalidJWTSource()
+        let cachingSource = CachingTokenSource(mockInvalidSource)
 
-        let request = ConnectionCredentials.Request(
+        let request = Token.Request(
             roomName: "test-room",
             participantName: "bob",
             participantIdentity: "bob-id"
         )
 
-        let response1 = try await cachingProvider.fetch(request)
-        let callCount1 = await mockInvalidProvider.callCount
+        let response1 = try await cachingSource.fetch(request)
+        let callCount1 = await mockInvalidSource.callCount
         XCTAssertEqual(callCount1, 1)
         XCTAssertFalse(response1.hasValidToken(), "Invalid token should not be considered valid")
 
-        let response2 = try await cachingProvider.fetch(request)
-        let callCount2 = await mockInvalidProvider.callCount
+        let response2 = try await cachingSource.fetch(request)
+        let callCount2 = await mockInvalidSource.callCount
         XCTAssertEqual(callCount2, 2)
         XCTAssertEqual(response2.participantToken, response1.participantToken)
 
-        let mockExpiredProvider = MockExpiredJWTProvider()
-        let cachingProviderExpired = CachingCredentialsProvider(mockExpiredProvider)
+        let mockExpiredSource = MockExpiredJWTSource()
+        let cachingSourceExpired = CachingTokenSource(mockExpiredSource)
 
-        let response3 = try await cachingProviderExpired.fetch(request)
-        let expiredCallCount1 = await mockExpiredProvider.callCount
+        let response3 = try await cachingSourceExpired.fetch(request)
+        let expiredCallCount1 = await mockExpiredSource.callCount
         XCTAssertEqual(expiredCallCount1, 1)
         XCTAssertFalse(response3.hasValidToken(), "Expired token should not be considered valid")
 
-        _ = try await cachingProviderExpired.fetch(request)
-        let expiredCallCount2 = await mockExpiredProvider.callCount
+        _ = try await cachingSourceExpired.fetch(request)
+        let expiredCallCount2 = await mockExpiredSource.callCount
         XCTAssertEqual(expiredCallCount2, 2)
     }
 
     func testCustomValidator() async throws {
-        let mockProvider = MockValidJWTProvider(participantName: "charlie")
+        let mockSource = MockValidJWTSource(participantName: "charlie")
 
-        let customValidator: CachingCredentialsProvider.Validator = { request, response in
+        let customValidator: CachingTokenSource.TokenValidator = { request, response in
             request.participantName == "charlie" && response.hasValidToken()
         }
 
-        let cachingProvider = CachingCredentialsProvider(mockProvider, validator: customValidator)
+        let cachingSource = CachingTokenSource(mockSource, validator: customValidator)
 
-        let charlieRequest = ConnectionCredentials.Request(
+        let charlieRequest = Token.Request(
             roomName: "test-room",
             participantName: "charlie",
             participantIdentity: "charlie-id"
         )
 
-        let response1 = try await cachingProvider.fetch(charlieRequest)
-        let callCount1 = await mockProvider.callCount
+        let response1 = try await cachingSource.fetch(charlieRequest)
+        let callCount1 = await mockSource.callCount
         XCTAssertEqual(callCount1, 1)
         XCTAssertTrue(response1.hasValidToken())
 
-        let response2 = try await cachingProvider.fetch(charlieRequest)
-        let callCount2 = await mockProvider.callCount
+        let response2 = try await cachingSource.fetch(charlieRequest)
+        let callCount2 = await mockSource.callCount
         XCTAssertEqual(callCount2, 1)
         XCTAssertEqual(response2.participantToken, response1.participantToken)
 
-        let aliceRequest = ConnectionCredentials.Request(
+        let aliceRequest = Token.Request(
             roomName: "test-room",
             participantName: "alice",
             participantIdentity: "alice-id"
         )
 
-        _ = try await cachingProvider.fetch(aliceRequest)
-        let callCount3 = await mockProvider.callCount
+        _ = try await cachingSource.fetch(aliceRequest)
+        let callCount3 = await mockSource.callCount
         XCTAssertEqual(callCount3, 2)
 
-        _ = try await cachingProvider.fetch(aliceRequest)
-        let callCount4 = await mockProvider.callCount
+        _ = try await cachingSource.fetch(aliceRequest)
+        let callCount4 = await mockSource.callCount
         XCTAssertEqual(callCount4, 3)
 
-        let tokenMockProvider = MockValidJWTProvider(participantName: "dave")
-        let tokenContentValidator: CachingCredentialsProvider.Validator = { request, response in
+        let tokenMockSource = MockValidJWTSource(participantName: "dave")
+        let tokenContentValidator: CachingTokenSource.TokenValidator = { request, response in
             request.roomName == "test-room" && response.hasValidToken()
         }
 
-        let tokenCachingProvider = CachingCredentialsProvider(tokenMockProvider, validator: tokenContentValidator)
+        let tokenCachingSource = CachingTokenSource(tokenMockSource, validator: tokenContentValidator)
 
-        let roomRequest = ConnectionCredentials.Request(
+        let roomRequest = Token.Request(
             roomName: "test-room",
             participantName: "dave",
             participantIdentity: "dave-id"
         )
 
-        _ = try await tokenCachingProvider.fetch(roomRequest)
-        let tokenCallCount1 = await tokenMockProvider.callCount
+        _ = try await tokenCachingSource.fetch(roomRequest)
+        let tokenCallCount1 = await tokenMockSource.callCount
         XCTAssertEqual(tokenCallCount1, 1)
 
-        _ = try await tokenCachingProvider.fetch(roomRequest)
-        let tokenCallCount2 = await tokenMockProvider.callCount
+        _ = try await tokenCachingSource.fetch(roomRequest)
+        let tokenCallCount2 = await tokenMockSource.callCount
         XCTAssertEqual(tokenCallCount2, 1)
 
-        let differentRoomRequest = ConnectionCredentials.Request(
+        let differentRoomRequest = Token.Request(
             roomName: "different-room",
             participantName: "dave",
             participantIdentity: "dave-id"
         )
 
-        _ = try await tokenCachingProvider.fetch(differentRoomRequest)
-        let tokenCallCount3 = await tokenMockProvider.callCount
+        _ = try await tokenCachingSource.fetch(differentRoomRequest)
+        let tokenCallCount3 = await tokenMockSource.callCount
         XCTAssertEqual(tokenCallCount3, 2)
 
-        _ = try await tokenCachingProvider.fetch(differentRoomRequest)
-        let tokenCallCount4 = await tokenMockProvider.callCount
+        _ = try await tokenCachingSource.fetch(differentRoomRequest)
+        let tokenCallCount4 = await tokenMockSource.callCount
         XCTAssertEqual(tokenCallCount4, 3)
     }
 
     func testConcurrentAccess() async throws {
-        let mockProvider = MockValidJWTProvider(participantName: "concurrent-test")
-        let cachingProvider = CachingCredentialsProvider(mockProvider)
+        let mockSource = MockValidJWTSource(participantName: "concurrent-test")
+        let cachingSource = CachingTokenSource(mockSource)
 
-        let request = ConnectionCredentials.Request(
+        let request = Token.Request(
             roomName: "concurrent-room",
             participantName: "concurrent-user",
             participantIdentity: "concurrent-id"
         )
 
-        let initialResponse = try await cachingProvider.fetch(request)
-        let initialCallCount = await mockProvider.callCount
+        let initialResponse = try await cachingSource.fetch(request)
+        let initialCallCount = await mockSource.callCount
         XCTAssertEqual(initialCallCount, 1)
 
-        async let fetch1 = cachingProvider.fetch(request)
-        async let fetch2 = cachingProvider.fetch(request)
-        async let fetch3 = cachingProvider.fetch(request)
+        async let fetch1 = cachingSource.fetch(request)
+        async let fetch2 = cachingSource.fetch(request)
+        async let fetch3 = cachingSource.fetch(request)
 
         let responses = try await [fetch1, fetch2, fetch3]
 
@@ -257,11 +257,11 @@ class ConnectionCredentialsTests: LKTestCase {
         XCTAssertEqual(responses[1].participantToken, initialResponse.participantToken)
         XCTAssertEqual(responses[2].participantToken, initialResponse.participantToken)
 
-        XCTAssertEqual(responses[0].serverUrl, initialResponse.serverUrl)
-        XCTAssertEqual(responses[1].serverUrl, initialResponse.serverUrl)
-        XCTAssertEqual(responses[2].serverUrl, initialResponse.serverUrl)
+        XCTAssertEqual(responses[0].serverURL, initialResponse.serverURL)
+        XCTAssertEqual(responses[1].serverURL, initialResponse.serverURL)
+        XCTAssertEqual(responses[2].serverURL, initialResponse.serverURL)
 
-        let finalCallCount = await mockProvider.callCount
+        let finalCallCount = await mockSource.callCount
         XCTAssertEqual(finalCallCount, 1)
     }
 }

From 3c37daa0c0b826ffb03bb675038e4f3cd2ff096b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Fri, 19 Sep 2025 09:11:02 +0200
Subject: [PATCH 15/28] Move Sandbox

---
 Sources/LiveKit/Auth/Sandbox.swift     | 35 ++++++++++++++++++++++++++
 Sources/LiveKit/Auth/TokenSource.swift | 25 +++---------------
 2 files changed, 39 insertions(+), 21 deletions(-)
 create mode 100644 Sources/LiveKit/Auth/Sandbox.swift

diff --git a/Sources/LiveKit/Auth/Sandbox.swift b/Sources/LiveKit/Auth/Sandbox.swift
new file mode 100644
index 000000000..2e7b5a6b5
--- /dev/null
+++ b/Sources/LiveKit/Auth/Sandbox.swift
@@ -0,0 +1,35 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Foundation
+
+/// `Sandbox` queries LiveKit Sandbox token server for credentials,
+/// which supports quick prototyping/getting started types of use cases.
+/// - Warning: This token endpoint is **INSECURE** and should **NOT** be used in production.
+public struct Sandbox: TokenEndpoint {
+    public let url = URL(string: "https://cloud-api.livekit.io/api/sandbox/connection-details")!
+    public var headers: [String: String] {
+        ["X-Sandbox-ID": id]
+    }
+
+    /// The sandbox ID provided by LiveKit Cloud.
+    public let id: String
+
+    /// Initialize with a sandbox ID from LiveKit Cloud.
+    public init(id: String) {
+        self.id = id.trimmingCharacters(in: CharacterSet(charactersIn: "\""))
+    }
+}
diff --git a/Sources/LiveKit/Auth/TokenSource.swift b/Sources/LiveKit/Auth/TokenSource.swift
index 39fa0429a..1a82d7816 100644
--- a/Sources/LiveKit/Auth/TokenSource.swift
+++ b/Sources/LiveKit/Auth/TokenSource.swift
@@ -18,6 +18,8 @@ import Foundation
 
 #warning("Fix camel case after deploying backend")
 
+// MARK: - Token
+
 /// `Token` represent the credentials needed for connecting to a new Room.
 /// - SeeAlso: [LiveKit's Authentication Documentation](https://docs.livekit.io/home/get-started/authentication/) for more information.
 public enum Token {
@@ -85,7 +87,7 @@ public enum Token {
     public typealias Literal = Response
 }
 
-// MARK: - Provider
+// MARK: - Source
 
 /// Protocol for types that can provide connection credentials.
 /// Implement this protocol to create custom credential providers (e.g., fetching from your backend API).
@@ -94,14 +96,13 @@ public protocol TokenSource: Sendable {
 }
 
 /// `Token.Literal` contains a single set of credentials, hard-coded or acquired from a static source.
-/// - Note: It does not support refreshing credentials.
 extension Token.Literal: TokenSource {
     public func fetch(_: Token.Request) async throws -> Token.Response {
         self
     }
 }
 
-// MARK: - Token Server
+// MARK: - Endpoint
 
 /// Protocol for token servers that fetch credentials via HTTP requests.
 /// Provides a default implementation of `fetch` that can be used to integrate with custom backend token generation endpoints.
@@ -142,24 +143,6 @@ public extension TokenEndpoint {
     }
 }
 
-/// `Sandbox` queries LiveKit Sandbox token server for credentials,
-/// which supports quick prototyping/getting started types of use cases.
-/// - Warning: This token endpoint is **INSECURE** and should **NOT** be used in production.
-public struct Sandbox: TokenEndpoint {
-    public let url = URL(string: "https://cloud-api.livekit.io/api/sandbox/connection-details")!
-    public var headers: [String: String] {
-        ["X-Sandbox-ID": id]
-    }
-
-    /// The sandbox ID provided by LiveKit Cloud.
-    public let id: String
-
-    /// Initialize with a sandbox ID from LiveKit Cloud.
-    public init(id: String) {
-        self.id = id.trimmingCharacters(in: CharacterSet(charactersIn: "\""))
-    }
-}
-
 // MARK: - Cache
 
 /// `CachingTokenSource` handles caching of credentials from any other `TokenSource` using configurable store.

From d664a5fa996a32973ae202bf52015071b9b4c11d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Fri, 19 Sep 2025 09:16:59 +0200
Subject: [PATCH 16/28] Public, comments

---
 Sources/LiveKit/Auth/TokenSource.swift | 30 ++++++++++++++++++--------
 1 file changed, 21 insertions(+), 9 deletions(-)

diff --git a/Sources/LiveKit/Auth/TokenSource.swift b/Sources/LiveKit/Auth/TokenSource.swift
index 1a82d7816..982dca2d0 100644
--- a/Sources/LiveKit/Auth/TokenSource.swift
+++ b/Sources/LiveKit/Auth/TokenSource.swift
@@ -26,18 +26,19 @@ public enum Token {
     /// Request parameters for generating connection credentials.
     public struct Request: Encodable, Sendable, Equatable {
         /// The name of the room being requested when generating credentials.
-        let roomName: String?
+        public let roomName: String?
         /// The name of the participant being requested for this client when generating credentials.
-        let participantName: String?
+        public let participantName: String?
         /// The identity of the participant being requested for this client when generating credentials.
-        let participantIdentity: String?
+        public let participantIdentity: String?
         /// Any participant metadata being included along with the credentials generation operation.
-        let participantMetadata: String?
+        public let participantMetadata: String?
         /// Any participant attributes being included along with the credentials generation operation.
-        let participantAttributes: [String: String]?
-        /// A `RoomConfiguration` object can be passed to request extra parameters should be included when generating connection credentials - dispatching agents, etc.
+        public let participantAttributes: [String: String]?
+        /// A `RoomConfiguration` object can be passed to request extra parameters when generating connection credentials.
+        /// Used for advanced room configuration like dispatching agents, setting room limits, etc.
         /// - SeeAlso: [Room Configuration Documentation](https://docs.livekit.io/home/get-started/authentication/#room-configuration) for more info.
-        let roomConfiguration: RoomConfiguration?
+        public let roomConfiguration: RoomConfiguration?
 
         // enum CodingKeys: String, CodingKey {
         //     case roomName = "room_name"
@@ -68,9 +69,9 @@ public enum Token {
     /// Response containing the credentials needed to connect to a room.
     public struct Response: Decodable, Sendable {
         /// The WebSocket URL for the LiveKit server.
-        let serverURL: URL
+        public let serverURL: URL
         /// The JWT token containing participant permissions and metadata.
-        let participantToken: String
+        public let participantToken: String
 
         enum CodingKeys: String, CodingKey {
             case serverURL = "serverUrl"
@@ -92,6 +93,10 @@ public enum Token {
 /// Protocol for types that can provide connection credentials.
 /// Implement this protocol to create custom credential providers (e.g., fetching from your backend API).
 public protocol TokenSource: Sendable {
+    /// Fetch connection credentials for the given request.
+    /// - Parameter request: The token request containing room and participant information
+    /// - Returns: A token response containing the server URL and participant token
+    /// - Throws: An error if the token generation fails
     func fetch(_ request: Token.Request) async throws -> Token.Response
 }
 
@@ -150,6 +155,10 @@ public actor CachingTokenSource: TokenSource, Loggable {
     /// A tuple containing the request and response that were cached.
     public typealias Cached = (Token.Request, Token.Response)
     /// A closure that validates whether cached credentials are still valid.
+    /// - Parameters:
+    ///   - request: The original token request
+    ///   - response: The cached token response
+    /// - Returns: `true` if the cached credentials are still valid, `false` otherwise
     public typealias TokenValidator = (Token.Request, Token.Response) -> Bool
 
     private let source: TokenSource
@@ -236,6 +245,9 @@ public actor InMemoryTokenStore: TokenStore {
 // MARK: - Validation
 
 public extension Token.Response {
+    /// Validates whether the JWT token is still valid.
+    /// - Parameter tolerance: Time tolerance in seconds for token expiration check (default: 60 seconds)
+    /// - Returns: `true` if the token is valid and not expired, `false` otherwise
     func hasValidToken(withTolerance tolerance: TimeInterval = 60) -> Bool {
         let parts = participantToken.components(separatedBy: ".")
         guard parts.count == 3 else {

From 5fc7ee16228a81effdee622d525362da39433b31 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Fri, 19 Sep 2025 09:25:32 +0200
Subject: [PATCH 17/28] Nitpicks

---
 Sources/LiveKit/Auth/TokenSource.swift | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Sources/LiveKit/Auth/TokenSource.swift b/Sources/LiveKit/Auth/TokenSource.swift
index 982dca2d0..4375ba08c 100644
--- a/Sources/LiveKit/Auth/TokenSource.swift
+++ b/Sources/LiveKit/Auth/TokenSource.swift
@@ -173,7 +173,7 @@ public actor CachingTokenSource: TokenSource, Loggable {
     public init(
         _ source: TokenSource,
         store: TokenStore = InMemoryTokenStore(),
-        validator: @escaping TokenValidator = { _, res in res.hasValidToken() }
+        validator: @escaping TokenValidator = { _, response in response.hasValidToken() }
     ) {
         self.source = source
         self.store = store
@@ -201,9 +201,9 @@ public actor CachingTokenSource: TokenSource, Loggable {
     }
 
     /// Get the cached credentials
-    /// - Returns: The cached credentials if found, nil otherwise
-    public func getCachedCredentials() async -> CachingTokenSource.Cached? {
-        await store.retrieve()
+    /// - Returns: The cached token if found, nil otherwise
+    public func cachedToken() async -> Token.Response? {
+        await store.retrieve()?.1
     }
 }
 

From f26073218a67aae49de2136d3619c63a9d3944f2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Fri, 19 Sep 2025 09:27:31 +0200
Subject: [PATCH 18/28] Change

---
 .changes/connection-credentials | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.changes/connection-credentials b/.changes/connection-credentials
index d60db7942..37cbf36c7 100644
--- a/.changes/connection-credentials
+++ b/.changes/connection-credentials
@@ -1 +1 @@
-patch type="added" "Abstract credential providers for easier token fetching"
+patch type="added" "Abstract token source for easier token fetching in production and faster integration with sandbox environment"

From b89ab16ff86c065e39ac38f24aba0090442d7dd2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Fri, 19 Sep 2025 10:35:38 +0200
Subject: [PATCH 19/28] JWT

---
 Package.swift                                 |  6 +-
 Package@swift-6.0.swift                       |  6 +-
 Sources/LiveKit/Auth/JWT.swift                | 99 +++++++++++++++++++
 Sources/LiveKit/Auth/TokenSource.swift        | 36 ++-----
 .../LiveKitTests/Auth/TokenSourceTests.swift  |  4 +-
 Tests/LiveKitTests/Support/Room.swift         | 12 +--
 .../LiveKitTests/Support/TokenGenerator.swift | 92 ++---------------
 7 files changed, 130 insertions(+), 125 deletions(-)
 create mode 100644 Sources/LiveKit/Auth/JWT.swift

diff --git a/Package.swift b/Package.swift
index eb1ec22fc..7d4ba7199 100644
--- a/Package.swift
+++ b/Package.swift
@@ -23,10 +23,9 @@ let package = Package(
         .package(url: "https://github.com/apple/swift-protobuf.git", from: "1.29.0"),
         .package(url: "https://github.com/apple/swift-log.git", from: "1.6.2"),
         .package(url: "https://github.com/apple/swift-collections.git", from: "1.1.0"),
+        .package(url: "https://github.com/vapor/jwt-kit.git", from: "4.13.5"),
         // Only used for DocC generation
         .package(url: "https://github.com/apple/swift-docc-plugin.git", from: "1.3.0"),
-        // Only used for Testing
-        .package(url: "https://github.com/vapor/jwt-kit.git", from: "4.13.4"),
     ],
     targets: [
         .target(
@@ -41,6 +40,7 @@ let package = Package(
                 .product(name: "DequeModule", package: "swift-collections"),
                 .product(name: "OrderedCollections", package: "swift-collections"),
                 .product(name: "Logging", package: "swift-log"),
+                .product(name: "JWTKit", package: "jwt-kit"),
                 "LKObjCHelpers",
             ],
             exclude: [
@@ -57,14 +57,12 @@ let package = Package(
             name: "LiveKitTests",
             dependencies: [
                 "LiveKit",
-                .product(name: "JWTKit", package: "jwt-kit"),
             ]
         ),
         .testTarget(
             name: "LiveKitTestsObjC",
             dependencies: [
                 "LiveKit",
-                .product(name: "JWTKit", package: "jwt-kit"),
             ]
         ),
     ],
diff --git a/Package@swift-6.0.swift b/Package@swift-6.0.swift
index b9076ef75..ab1f670ef 100644
--- a/Package@swift-6.0.swift
+++ b/Package@swift-6.0.swift
@@ -24,10 +24,9 @@ let package = Package(
         .package(url: "https://github.com/apple/swift-protobuf.git", from: "1.29.0"),
         .package(url: "https://github.com/apple/swift-log.git", from: "1.6.2"),
         .package(url: "https://github.com/apple/swift-collections.git", from: "1.1.0"),
+        .package(url: "https://github.com/vapor/jwt-kit.git", from: "4.13.5"),
         // Only used for DocC generation
         .package(url: "https://github.com/apple/swift-docc-plugin.git", from: "1.3.0"),
-        // Only used for Testing
-        .package(url: "https://github.com/vapor/jwt-kit.git", from: "4.13.4"),
     ],
     targets: [
         .target(
@@ -42,6 +41,7 @@ let package = Package(
                 .product(name: "DequeModule", package: "swift-collections"),
                 .product(name: "OrderedCollections", package: "swift-collections"),
                 .product(name: "Logging", package: "swift-log"),
+                .product(name: "JWTKit", package: "jwt-kit"),
                 "LKObjCHelpers",
             ],
             exclude: [
@@ -58,14 +58,12 @@ let package = Package(
             name: "LiveKitTests",
             dependencies: [
                 "LiveKit",
-                .product(name: "JWTKit", package: "jwt-kit"),
             ]
         ),
         .testTarget(
             name: "LiveKitTestsObjC",
             dependencies: [
                 "LiveKit",
-                .product(name: "JWTKit", package: "jwt-kit"),
             ]
         ),
     ],
diff --git a/Sources/LiveKit/Auth/JWT.swift b/Sources/LiveKit/Auth/JWT.swift
new file mode 100644
index 000000000..b0531594f
--- /dev/null
+++ b/Sources/LiveKit/Auth/JWT.swift
@@ -0,0 +1,99 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import JWTKit
+
+public struct LiveKitJWTPayload: JWTPayload, Codable, Equatable {
+    public struct VideoGrant: Codable, Equatable {
+        /// Name of the room, must be set for admin or join permissions
+        public let room: String?
+        /// Permission to create a room
+        public let roomCreate: Bool?
+        /// Permission to join a room as a participant, room must be set
+        public let roomJoin: Bool?
+        /// Permission to list rooms
+        public let roomList: Bool?
+        /// Permission to start a recording
+        public let roomRecord: Bool?
+        /// Permission to control a specific room, room must be set
+        public let roomAdmin: Bool?
+
+        /// Allow participant to publish. If neither canPublish or canSubscribe is set, both publish and subscribe are enabled
+        public let canPublish: Bool?
+        /// Allow participant to subscribe to other tracks
+        public let canSubscribe: Bool?
+        /// Allow participants to publish data, defaults to true if not set
+        public let canPublishData: Bool?
+        /// Allowed sources for publishing
+        public let canPublishSources: [String]?
+        /// Participant isn't visible to others
+        public let hidden: Bool?
+        /// Participant is recording the room, when set, allows room to indicate it's being recorded
+        public let recorder: Bool?
+
+        public init(room: String? = nil,
+                    roomCreate: Bool? = nil,
+                    roomJoin: Bool? = nil,
+                    roomList: Bool? = nil,
+                    roomRecord: Bool? = nil,
+                    roomAdmin: Bool? = nil,
+                    canPublish: Bool? = nil,
+                    canSubscribe: Bool? = nil,
+                    canPublishData: Bool? = nil,
+                    canPublishSources: [String]? = nil,
+                    hidden: Bool? = nil,
+                    recorder: Bool? = nil)
+        {
+            self.room = room
+            self.roomCreate = roomCreate
+            self.roomJoin = roomJoin
+            self.roomList = roomList
+            self.roomRecord = roomRecord
+            self.roomAdmin = roomAdmin
+            self.canPublish = canPublish
+            self.canSubscribe = canSubscribe
+            self.canPublishData = canPublishData
+            self.canPublishSources = canPublishSources
+            self.hidden = hidden
+            self.recorder = recorder
+        }
+    }
+
+    /// Expiration time claim
+    public let exp: ExpirationClaim
+    /// Issuer claim
+    public let iss: IssuerClaim
+    /// Not before claim
+    public let nbf: NotBeforeClaim
+    /// Subject claim
+    public let sub: SubjectClaim
+
+    /// Participant name
+    public let name: String?
+    /// Participant metadata
+    public let metadata: String?
+    /// Video grants for the participant
+    public let video: VideoGrant?
+
+    public func verify(using _: JWTSigner) throws {
+        try nbf.verifyNotBefore()
+        try exp.verifyNotExpired()
+    }
+
+    static func fromUnverified(token: String) -> Self? {
+        try? JWTSigners().unverified(token, as: Self.self)
+    }
+}
diff --git a/Sources/LiveKit/Auth/TokenSource.swift b/Sources/LiveKit/Auth/TokenSource.swift
index 4375ba08c..866f2e176 100644
--- a/Sources/LiveKit/Auth/TokenSource.swift
+++ b/Sources/LiveKit/Auth/TokenSource.swift
@@ -249,39 +249,23 @@ public extension Token.Response {
     /// - Parameter tolerance: Time tolerance in seconds for token expiration check (default: 60 seconds)
     /// - Returns: `true` if the token is valid and not expired, `false` otherwise
     func hasValidToken(withTolerance tolerance: TimeInterval = 60) -> Bool {
-        let parts = participantToken.components(separatedBy: ".")
-        guard parts.count == 3 else {
+        guard let jwt = jwt() else {
             return false
         }
 
-        let payloadData = parts[1]
-
-        struct JWTPayload: Decodable {
-            let nbf: Double
-            let exp: Double
-        }
-
-        guard let payloadJSON = payloadData.base64Decode(),
-              let payload = try? JSONDecoder().decode(JWTPayload.self, from: payloadJSON)
-        else {
+        do {
+            try jwt.nbf.verifyNotBefore()
+            try jwt.exp.verifyNotExpired(currentDate: Date().addingTimeInterval(tolerance))
+        } catch {
             return false
         }
 
-        let now = Date().timeIntervalSince1970
-        return payload.nbf <= now && payload.exp > now - tolerance
+        return true
     }
-}
-
-private extension String {
-    func base64Decode() -> Data? {
-        var base64 = self
-        base64 = base64.replacingOccurrences(of: "-", with: "+")
-        base64 = base64.replacingOccurrences(of: "_", with: "/")
-
-        while base64.count % 4 != 0 {
-            base64.append("=")
-        }
 
-        return Data(base64Encoded: base64)
+    /// Extracts the JWT payload from the participant token.
+    /// - Returns: The JWT payload if found, nil otherwise
+    func jwt() -> LiveKitJWTPayload? {
+        LiveKitJWTPayload.fromUnverified(token: participantToken)
     }
 }
diff --git a/Tests/LiveKitTests/Auth/TokenSourceTests.swift b/Tests/LiveKitTests/Auth/TokenSourceTests.swift
index db51079ec..37841af17 100644
--- a/Tests/LiveKitTests/Auth/TokenSourceTests.swift
+++ b/Tests/LiveKitTests/Auth/TokenSourceTests.swift
@@ -37,7 +37,7 @@ class TokenSourceTests: LKTestCase {
                 identity: request.participantIdentity ?? "test-identity"
             )
             tokenGenerator.name = request.participantName ?? participantName
-            tokenGenerator.videoGrant = VideoGrant(room: request.roomName ?? "test-room", roomJoin: true)
+            tokenGenerator.videoGrant = LiveKitJWTPayload.VideoGrant(room: request.roomName ?? "test-room", roomJoin: true)
 
             let token = try tokenGenerator.sign()
 
@@ -76,7 +76,7 @@ class TokenSourceTests: LKTestCase {
                 ttl: -60
             )
             tokenGenerator.name = request.participantName ?? "test-participant"
-            tokenGenerator.videoGrant = VideoGrant(room: request.roomName ?? "test-room", roomJoin: true)
+            tokenGenerator.videoGrant = LiveKitJWTPayload.VideoGrant(room: request.roomName ?? "test-room", roomJoin: true)
 
             let token = try tokenGenerator.sign()
 
diff --git a/Tests/LiveKitTests/Support/Room.swift b/Tests/LiveKitTests/Support/Room.swift
index b9cdc33d4..3493e97a2 100644
--- a/Tests/LiveKitTests/Support/Room.swift
+++ b/Tests/LiveKitTests/Support/Room.swift
@@ -76,12 +76,12 @@ extension LKTestCase {
                                             apiSecret: apiSecret,
                                             identity: identity)
 
-        tokenGenerator.videoGrant = VideoGrant(room: room,
-                                               roomJoin: true,
-                                               canPublish: canPublish,
-                                               canSubscribe: canSubscribe,
-                                               canPublishData: canPublishData,
-                                               canPublishSources: canPublishSources.map(String.init))
+        tokenGenerator.videoGrant = LiveKitJWTPayload.VideoGrant(room: room,
+                                                                 roomJoin: true,
+                                                                 canPublish: canPublish,
+                                                                 canSubscribe: canSubscribe,
+                                                                 canPublishData: canPublishData,
+                                                                 canPublishSources: canPublishSources.map(String.init))
         return try tokenGenerator.sign()
     }
 
diff --git a/Tests/LiveKitTests/Support/TokenGenerator.swift b/Tests/LiveKitTests/Support/TokenGenerator.swift
index db304b27d..ccd22ed8c 100644
--- a/Tests/LiveKitTests/Support/TokenGenerator.swift
+++ b/Tests/LiveKitTests/Support/TokenGenerator.swift
@@ -16,83 +16,9 @@
 
 import Foundation
 import JWTKit
-
-public struct VideoGrant: Codable, Equatable {
-    /** name of the room, must be set for admin or join permissions */
-    let room: String?
-    /** permission to create a room */
-    let roomCreate: Bool?
-    /** permission to join a room as a participant, room must be set */
-    let roomJoin: Bool?
-    /** permission to list rooms */
-    let roomList: Bool?
-    /** permission to start a recording */
-    let roomRecord: Bool?
-    /** permission to control a specific room, room must be set */
-    let roomAdmin: Bool?
-
-    /**
-     * allow participant to publish. If neither canPublish or canSubscribe is set,
-     * both publish and subscribe are enabled
-     */
-    let canPublish: Bool?
-    /** allow participant to subscribe to other tracks */
-    let canSubscribe: Bool?
-    /**
-     * allow participants to publish data, defaults to true if not set
-     */
-    let canPublishData: Bool?
-    /** allowed sources for publishing */
-    let canPublishSources: [String]? // String as returned in the JWT
-    /** participant isn't visible to others */
-    let hidden: Bool?
-    /** participant is recording the room, when set, allows room to indicate it's being recorded */
-    let recorder: Bool?
-
-    init(room: String? = nil,
-         roomCreate: Bool? = nil,
-         roomJoin: Bool? = nil,
-         roomList: Bool? = nil,
-         roomRecord: Bool? = nil,
-         roomAdmin: Bool? = nil,
-         canPublish: Bool? = nil,
-         canSubscribe: Bool? = nil,
-         canPublishData: Bool? = nil,
-         canPublishSources: [String]? = nil,
-         hidden: Bool? = nil,
-         recorder: Bool? = nil)
-    {
-        self.room = room
-        self.roomCreate = roomCreate
-        self.roomJoin = roomJoin
-        self.roomList = roomList
-        self.roomRecord = roomRecord
-        self.roomAdmin = roomAdmin
-        self.canPublish = canPublish
-        self.canSubscribe = canSubscribe
-        self.canPublishData = canPublishData
-        self.canPublishSources = canPublishSources
-        self.hidden = hidden
-        self.recorder = recorder
-    }
-}
+@testable import LiveKit
 
 public class TokenGenerator {
-    private struct Payload: JWTPayload, Equatable {
-        let exp: ExpirationClaim
-        let iss: IssuerClaim
-        let nbf: NotBeforeClaim
-        let sub: SubjectClaim
-
-        let name: String?
-        let metadata: String?
-        let video: VideoGrant?
-
-        func verify(using _: JWTSigner) throws {
-            fatalError("not implemented")
-        }
-    }
-
     // 30 mins
     static let defaultTTL: TimeInterval = 30 * 60
 
@@ -104,7 +30,7 @@ public class TokenGenerator {
     public var ttl: TimeInterval
     public var name: String?
     public var metadata: String?
-    public var videoGrant: VideoGrant?
+    public var videoGrant: LiveKitJWTPayload.VideoGrant?
 
     // MARK: - Private
 
@@ -127,13 +53,13 @@ public class TokenGenerator {
 
         let n = Date().timeIntervalSince1970
 
-        let p = Payload(exp: .init(value: Date(timeIntervalSince1970: floor(n + ttl))),
-                        iss: .init(stringLiteral: apiKey),
-                        nbf: .init(value: Date(timeIntervalSince1970: floor(n))),
-                        sub: .init(stringLiteral: identity),
-                        name: name,
-                        metadata: metadata,
-                        video: videoGrant)
+        let p = LiveKitJWTPayload(exp: .init(value: Date(timeIntervalSince1970: floor(n + ttl))),
+                                  iss: .init(stringLiteral: apiKey),
+                                  nbf: .init(value: Date(timeIntervalSince1970: floor(n))),
+                                  sub: .init(stringLiteral: identity),
+                                  name: name,
+                                  metadata: metadata,
+                                  video: videoGrant)
 
         return try signers.sign(p)
     }

From df57f3c17b02719bdcda8a80890b5b1207a5d85a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Fri, 19 Sep 2025 11:11:02 +0200
Subject: [PATCH 20/28] Filter

---
 Sources/LiveKit/Auth/Sandbox.swift | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Sources/LiveKit/Auth/Sandbox.swift b/Sources/LiveKit/Auth/Sandbox.swift
index 2e7b5a6b5..e090d625a 100644
--- a/Sources/LiveKit/Auth/Sandbox.swift
+++ b/Sources/LiveKit/Auth/Sandbox.swift
@@ -30,6 +30,6 @@ public struct Sandbox: TokenEndpoint {
 
     /// Initialize with a sandbox ID from LiveKit Cloud.
     public init(id: String) {
-        self.id = id.trimmingCharacters(in: CharacterSet(charactersIn: "\""))
+        self.id = id.trimmingCharacters(in: .alphanumerics.inverted)
     }
 }

From f342b174fcedf174a874686fdb899dcd14b20f07 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Thu, 18 Sep 2025 12:30:02 +0200
Subject: [PATCH 21/28] Move basic Agent files

---
 Sources/LiveKit/Agent/Agent.swift             |  49 +++++
 Sources/LiveKit/Agent/Chat/Message.swift      |  41 ++++
 .../Agent/Chat/Receive/MessageReceiver.swift  |  27 +++
 .../TranscriptionDelegateReceiver.swift       |  69 ++++++
 .../Receive/TranscriptionStreamReceiver.swift | 173 +++++++++++++++
 .../Agent/Chat/Send/MessageSender.swift       |  27 +++
 .../Agent/Chat/Send/TextMessageSender.swift   |  56 +++++
 .../Agent/Conversation+Environment.swift      |  63 ++++++
 Sources/LiveKit/Agent/Conversation.swift      | 200 ++++++++++++++++++
 Sources/LiveKit/Agent/LocalMedia.swift        | 165 +++++++++++++++
 .../LiveKit/Support/ObservableObject+.swift   |  34 +++
 11 files changed, 904 insertions(+)
 create mode 100644 Sources/LiveKit/Agent/Agent.swift
 create mode 100644 Sources/LiveKit/Agent/Chat/Message.swift
 create mode 100644 Sources/LiveKit/Agent/Chat/Receive/MessageReceiver.swift
 create mode 100644 Sources/LiveKit/Agent/Chat/Receive/TranscriptionDelegateReceiver.swift
 create mode 100644 Sources/LiveKit/Agent/Chat/Receive/TranscriptionStreamReceiver.swift
 create mode 100644 Sources/LiveKit/Agent/Chat/Send/MessageSender.swift
 create mode 100644 Sources/LiveKit/Agent/Chat/Send/TextMessageSender.swift
 create mode 100644 Sources/LiveKit/Agent/Conversation+Environment.swift
 create mode 100644 Sources/LiveKit/Agent/Conversation.swift
 create mode 100644 Sources/LiveKit/Agent/LocalMedia.swift
 create mode 100644 Sources/LiveKit/Support/ObservableObject+.swift

diff --git a/Sources/LiveKit/Agent/Agent.swift b/Sources/LiveKit/Agent/Agent.swift
new file mode 100644
index 000000000..70457f252
--- /dev/null
+++ b/Sources/LiveKit/Agent/Agent.swift
@@ -0,0 +1,49 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Foundation
+import LiveKit
+
+@MainActor
+open class Agent: ObservableObject {
+    @Published public private(set) var state: AgentState = .idle
+
+    @Published public private(set) var audioTrack: (any AudioTrack)?
+    @Published public private(set) var avatarVideoTrack: (any VideoTrack)?
+
+    public let participant: Participant
+
+    public init(participant: Participant) {
+        self.participant = participant
+        observe(participant)
+    }
+
+    private func observe(_ participant: Participant) {
+        Task { [weak self] in
+            for await _ in participant.changes {
+                guard let self else { return }
+
+                state = participant.agentState
+                updateTracks(of: participant)
+            }
+        }
+    }
+
+    private func updateTracks(of participant: Participant) {
+        audioTrack = participant.audioTracks.first(where: { $0.source == .microphone })?.track as? AudioTrack
+        avatarVideoTrack = participant.avatarWorker?.firstCameraVideoTrack
+    }
+}
diff --git a/Sources/LiveKit/Agent/Chat/Message.swift b/Sources/LiveKit/Agent/Chat/Message.swift
new file mode 100644
index 000000000..529728c1c
--- /dev/null
+++ b/Sources/LiveKit/Agent/Chat/Message.swift
@@ -0,0 +1,41 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Foundation
+
+/// A message received from the agent.
+public struct ReceivedMessage: Identifiable, Equatable, Codable, Sendable {
+    public let id: String
+    public let timestamp: Date
+    public let content: Content
+
+    public enum Content: Equatable, Codable, Sendable {
+        case agentTranscript(String)
+        case userTranscript(String)
+        case userInput(String)
+    }
+}
+
+/// A message sent to the agent.
+public struct SentMessage: Identifiable, Equatable, Codable, Sendable {
+    public let id: String
+    public let timestamp: Date
+    public let content: Content
+
+    public enum Content: Equatable, Codable, Sendable {
+        case userInput(String)
+    }
+}
diff --git a/Sources/LiveKit/Agent/Chat/Receive/MessageReceiver.swift b/Sources/LiveKit/Agent/Chat/Receive/MessageReceiver.swift
new file mode 100644
index 000000000..2344be30e
--- /dev/null
+++ b/Sources/LiveKit/Agent/Chat/Receive/MessageReceiver.swift
@@ -0,0 +1,27 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Foundation
+
+/// A protocol that defines a message receiver.
+///
+/// A message receiver is responsible for creating a stream of messages from the agent.
+/// It is used to receive messages from the agent and update the message feed.
+///
+/// - SeeAlso: ``ReceivedMessage``
+public protocol MessageReceiver: Sendable {
+    func messages() async throws -> AsyncStream<ReceivedMessage>
+}
diff --git a/Sources/LiveKit/Agent/Chat/Receive/TranscriptionDelegateReceiver.swift b/Sources/LiveKit/Agent/Chat/Receive/TranscriptionDelegateReceiver.swift
new file mode 100644
index 000000000..824d29a03
--- /dev/null
+++ b/Sources/LiveKit/Agent/Chat/Receive/TranscriptionDelegateReceiver.swift
@@ -0,0 +1,69 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Foundation
+import LiveKit
+
+/// An actor that receives transcription messages from the room and yields them as messages.
+///
+/// Room delegate methods are called multiple times for each message, with a stable message ID
+/// that can be direcly used for diffing.
+///
+/// Example:
+/// ```
+/// { id: "1", content: "Hello" }
+/// { id: "1", content: "Hello world!" }
+/// ```
+@available(*, deprecated, message: "Use TranscriptionStreamReceiver compatible with livekit-agents 1.0")
+actor TranscriptionDelegateReceiver: MessageReceiver, RoomDelegate {
+    private let room: Room
+    private var continuation: AsyncStream<ReceivedMessage>.Continuation?
+
+    init(room: Room) {
+        self.room = room
+        room.add(delegate: self)
+    }
+
+    deinit {
+        room.remove(delegate: self)
+    }
+
+    /// Creates a new message stream for the transcription delegate receiver.
+    func messages() -> AsyncStream<ReceivedMessage> {
+        let (stream, continuation) = AsyncStream.makeStream(of: ReceivedMessage.self)
+        self.continuation = continuation
+        return stream
+    }
+
+    nonisolated func room(_: Room, participant: Participant, trackPublication _: TrackPublication, didReceiveTranscriptionSegments segments: [TranscriptionSegment]) {
+        segments
+            .filter { !$0.text.isEmpty }
+            .forEach { segment in
+                let message = ReceivedMessage(
+                    id: segment.id,
+                    timestamp: segment.lastReceivedTime,
+                    content: participant.isAgent ? .agentTranscript(segment.text) : .userTranscript(segment.text)
+                )
+                Task {
+                    await yield(message)
+                }
+            }
+    }
+
+    private func yield(_ message: ReceivedMessage) {
+        continuation?.yield(message)
+    }
+}
diff --git a/Sources/LiveKit/Agent/Chat/Receive/TranscriptionStreamReceiver.swift b/Sources/LiveKit/Agent/Chat/Receive/TranscriptionStreamReceiver.swift
new file mode 100644
index 000000000..9ac2a1ce1
--- /dev/null
+++ b/Sources/LiveKit/Agent/Chat/Receive/TranscriptionStreamReceiver.swift
@@ -0,0 +1,173 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Foundation
+import LiveKit
+
+/// An actor that converts raw text streams from the LiveKit `Room` into `Message` objects.
+/// - Note: Streams are supported by `livekit-agents` >= 1.0.0.
+/// - SeeAlso: ``TranscriptionDelegateReceiver``
+///
+/// For agent messages, new text stream is emitted for each message, and the stream is closed when the message is finalized.
+/// Each agent message is delivered in chunks, that are accumulated and published into the message stream.
+///
+/// For user messages, the full transcription is sent each time, but may be updated until finalized.
+///
+/// The ID of the segment is stable and unique across the lifetime of the message.
+/// This ID can be used directly for `Identifiable` conformance.
+///
+/// Example text stream for agent messages:
+/// ```
+/// { segment_id: "1", content: "Hello" }
+/// { segment_id: "1", content: " world" }
+/// { segment_id: "1", content: "!" }
+/// { segment_id: "2", content: "Hello" }
+/// { segment_id: "2", content: " Apple" }
+/// { segment_id: "2", content: "!" }
+/// ```
+///
+/// Example text stream for user messages:
+/// ```
+/// { segment_id: "3", content: "Hello" }
+/// { segment_id: "3", content: "Hello world!" }
+/// { segment_id: "4", content: "Hello" }
+/// { segment_id: "4", content: "Hello Apple!" }
+/// ```
+///
+/// Example output:
+/// ```
+/// Message(id: "1", timestamp: 2025-01-01 12:00:00 +0000, content: .agentTranscript("Hello world!"))
+/// Message(id: "2", timestamp: 2025-01-01 12:00:10 +0000, content: .agentTranscript("Hello Apple!"))
+/// Message(id: "3", timestamp: 2025-01-01 12:00:20 +0000, content: .userTranscript("Hello world!"))
+/// Message(id: "4", timestamp: 2025-01-01 12:00:30 +0000, content: .userTranscript("Hello Apple!"))
+/// ```
+///
+actor TranscriptionStreamReceiver: MessageReceiver {
+    private struct PartialMessageID: Hashable {
+        let segmentID: String
+        let participantID: Participant.Identity
+    }
+
+    private struct PartialMessage {
+        var content: String
+        let timestamp: Date
+        var streamID: String
+
+        mutating func appendContent(_ newContent: String) {
+            content += newContent
+        }
+
+        mutating func replaceContent(_ newContent: String, streamID: String) {
+            content = newContent
+            self.streamID = streamID
+        }
+    }
+
+    private let transcriptionTopic = "lk.transcription"
+    private enum TranscriptionAttributes: String {
+        case final = "lk.transcription_final"
+        case segment = "lk.segment_id"
+    }
+
+    private let room: Room
+
+    private lazy var partialMessages: [PartialMessageID: PartialMessage] = [:]
+
+    init(room: Room) {
+        self.room = room
+    }
+
+    /// Creates a new message stream for the chat topic.
+    func messages() async throws -> AsyncStream<ReceivedMessage> {
+        let (stream, continuation) = AsyncStream.makeStream(of: ReceivedMessage.self)
+
+        try await room.registerTextStreamHandler(for: transcriptionTopic) { [weak self] reader, participantIdentity in
+            guard let self else { return }
+            for try await message in reader where !message.isEmpty {
+                await continuation.yield(processIncoming(partialMessage: message, reader: reader, participantIdentity: participantIdentity))
+            }
+        }
+
+        continuation.onTermination = { [weak self] _ in
+            Task {
+                guard let self else { return }
+                await self.room.unregisterTextStreamHandler(for: self.transcriptionTopic)
+            }
+        }
+
+        return stream
+    }
+
+    /// Aggregates the incoming text into a message, storing the partial content in the `partialMessages` dictionary.
+    /// - Note: When the message is finalized, or a new message is started, the dictionary is purged to limit memory usage.
+    private func processIncoming(partialMessage message: String, reader: TextStreamReader, participantIdentity: Participant.Identity) -> ReceivedMessage {
+        let segmentID = reader.info.attributes[TranscriptionAttributes.segment.rawValue] ?? reader.info.id
+        let participantID = participantIdentity
+        let partialID = PartialMessageID(segmentID: segmentID, participantID: participantID)
+
+        let currentStreamID = reader.info.id
+
+        let timestamp: Date
+        let updatedContent: String
+
+        if var existingMessage = partialMessages[partialID] {
+            // Update existing message
+            if existingMessage.streamID == currentStreamID {
+                // Same stream, append content
+                existingMessage.appendContent(message)
+            } else {
+                // Different stream for same segment, replace content
+                existingMessage.replaceContent(message, streamID: currentStreamID)
+            }
+            updatedContent = existingMessage.content
+            timestamp = existingMessage.timestamp
+            partialMessages[partialID] = existingMessage
+        } else {
+            // This is a new message
+            updatedContent = message
+            timestamp = reader.info.timestamp
+            partialMessages[partialID] = PartialMessage(
+                content: updatedContent,
+                timestamp: timestamp,
+                streamID: currentStreamID
+            )
+            cleanupPreviousTurn(participantIdentity, exceptSegmentID: segmentID)
+        }
+
+        let isFinal = reader.info.attributes[TranscriptionAttributes.final.rawValue] == "true"
+        if isFinal {
+            partialMessages[partialID] = nil
+        }
+
+        let newOrUpdatedMessage = ReceivedMessage(
+            id: segmentID,
+            timestamp: timestamp,
+            content: participantIdentity == room.localParticipant.identity ? .userTranscript(updatedContent) : .agentTranscript(updatedContent)
+        )
+
+        return newOrUpdatedMessage
+    }
+
+    private func cleanupPreviousTurn(_ participantID: Participant.Identity, exceptSegmentID: String) {
+        let keysToRemove = partialMessages.keys.filter {
+            $0.participantID == participantID && $0.segmentID != exceptSegmentID
+        }
+
+        for key in keysToRemove {
+            partialMessages[key] = nil
+        }
+    }
+}
diff --git a/Sources/LiveKit/Agent/Chat/Send/MessageSender.swift b/Sources/LiveKit/Agent/Chat/Send/MessageSender.swift
new file mode 100644
index 000000000..fe78232c0
--- /dev/null
+++ b/Sources/LiveKit/Agent/Chat/Send/MessageSender.swift
@@ -0,0 +1,27 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Foundation
+
+/// A protocol that defines a message sender.
+///
+/// A message sender is responsible for sending messages to the agent.
+/// It is used to send messages to the agent and update the message feed.
+///
+/// - SeeAlso: ``SentMessage``
+public protocol MessageSender: Sendable {
+    func send(_ message: SentMessage) async throws
+}
diff --git a/Sources/LiveKit/Agent/Chat/Send/TextMessageSender.swift b/Sources/LiveKit/Agent/Chat/Send/TextMessageSender.swift
new file mode 100644
index 000000000..af4bc6fb1
--- /dev/null
+++ b/Sources/LiveKit/Agent/Chat/Send/TextMessageSender.swift
@@ -0,0 +1,56 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Foundation
+import LiveKit
+
+/// An actor that sends local messages to the agent.
+/// Currently, it only supports sending text messages.
+///
+/// It also serves as the loopback for the local messages,
+/// so that they can be displayed in the message feed
+/// without relying on the agent-side transcription.
+actor TextMessageSender: MessageSender, MessageReceiver {
+    private let room: Room
+    private let topic: String
+
+    private var messageContinuation: AsyncStream<ReceivedMessage>.Continuation?
+
+    init(room: Room, topic: String = "lk.chat") {
+        self.room = room
+        self.topic = topic
+    }
+
+    func send(_ message: SentMessage) async throws {
+        guard case let .userInput(text) = message.content else { return }
+
+        try await room.localParticipant.sendText(text, for: topic)
+
+        let loopbackMessage = ReceivedMessage(
+            id: message.id,
+            timestamp: message.timestamp,
+            content: .userInput(text)
+        )
+
+        messageContinuation?.yield(loopbackMessage)
+    }
+
+    func messages() async throws -> AsyncStream<ReceivedMessage> {
+        let (stream, continuation) = AsyncStream<ReceivedMessage>.makeStream()
+        messageContinuation = continuation
+        return stream
+    }
+}
diff --git a/Sources/LiveKit/Agent/Conversation+Environment.swift b/Sources/LiveKit/Agent/Conversation+Environment.swift
new file mode 100644
index 000000000..e2feba7c3
--- /dev/null
+++ b/Sources/LiveKit/Agent/Conversation+Environment.swift
@@ -0,0 +1,63 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import SwiftUI
+
+extension EnvironmentValues {
+    @Entry var agentName: String? = nil
+}
+
+@MainActor
+@propertyWrapper
+struct LKConversation: DynamicProperty {
+    @EnvironmentObject private var conversation: Conversation
+
+    var wrappedValue: Conversation {
+        conversation
+    }
+}
+
+@MainActor
+@propertyWrapper
+struct LKLocalMedia: DynamicProperty {
+    @EnvironmentObject private var localMedia: LocalMedia
+
+    var wrappedValue: LocalMedia {
+        localMedia
+    }
+}
+
+@MainActor
+@propertyWrapper
+struct LKAgent: DynamicProperty {
+    @EnvironmentObject private var conversation: Conversation
+    @Environment(\.agentName) private var environmentName
+
+    let agentName: String?
+
+    init(named agentName: String? = nil) {
+        self.agentName = agentName
+    }
+
+    var wrappedValue: Agent? {
+        if let agentName {
+            return conversation.agent(named: agentName)
+        } else if let environmentName {
+            return conversation.agent(named: environmentName)
+        }
+        return conversation.agents.values.first
+    }
+}
diff --git a/Sources/LiveKit/Agent/Conversation.swift b/Sources/LiveKit/Agent/Conversation.swift
new file mode 100644
index 000000000..8edef675b
--- /dev/null
+++ b/Sources/LiveKit/Agent/Conversation.swift
@@ -0,0 +1,200 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Collections
+import Foundation
+import LiveKit
+
+@MainActor
+open class Conversation: ObservableObject {
+    // MARK: - Error
+
+    public enum Error: LocalizedError {
+        case agentNotConnected
+        case failedToConnect(Swift.Error)
+        case failedToSend(Swift.Error)
+
+        public var errorDescription: String? {
+            "TODO"
+        }
+    }
+
+    // MARK: - State
+
+    @Published public private(set) var error: Error?
+
+    @Published public private(set) var connectionState: ConnectionState = .disconnected
+    @Published public private(set) var isListening = false
+    public var isReady: Bool {
+        switch connectionState {
+        case .disconnected where isListening,
+             .connecting where isListening,
+             .connected,
+             .reconnecting:
+            true
+        default:
+            false
+        }
+    }
+
+    @Published public private(set) var agents: [Participant.Identity: Agent] = [:]
+    public var hasAgents: Bool { !agents.isEmpty }
+
+    @Published public private(set) var messages: OrderedDictionary<ReceivedMessage.ID, ReceivedMessage> = [:]
+
+    // MARK: - Dependencies
+
+    public let room: Room
+
+    private let credentials: any CredentialsProvider
+    private let senders: [any MessageSender]
+    private let receivers: [any MessageReceiver]
+
+    // MARK: - Internal state
+
+    private var waitForAgentTask: Task<Void, Swift.Error>?
+
+    // MARK: - Init
+
+    public init(credentials: CredentialsProvider, room: Room = .init(), agentName: String? = nil, senders: [any MessageSender]? = nil, receivers: [any MessageReceiver]? = nil) {
+        self.credentials = credentials
+        self.room = room
+
+        let textMessageSender = TextMessageSender(room: room)
+        let senders = senders ?? [textMessageSender]
+        let receivers = receivers ?? [textMessageSender, TranscriptionStreamReceiver(room: room)]
+
+        self.senders = senders
+        self.receivers = receivers
+
+        observe(room: room, agentName: agentName)
+        observe(receivers: receivers)
+    }
+
+    private func observe(room: Room, agentName _: String?) {
+        Task { [weak self] in
+            for await _ in room.changes {
+                guard let self else { return }
+
+                connectionState = room.connectionState
+                updateAgents(in: room)
+            }
+        }
+    }
+
+    private func updateAgents(in room: Room) {
+        let agentParticipants = room.agentParticipants
+
+        var newAgents: [Participant.Identity: Agent] = [:]
+
+        for (identity, participant) in agentParticipants {
+            if let existingAgent = agents[identity] {
+                newAgents[identity] = existingAgent
+            } else {
+                let newAgent = Agent(participant: participant)
+                newAgents[identity] = newAgent
+            }
+        }
+
+        agents = newAgents
+    }
+
+    private func observe(receivers: [any MessageReceiver]) {
+        for receiver in receivers {
+            Task { [weak self] in
+                for await message in try await receiver.messages() {
+                    guard let self else { return }
+                    messages.updateValue(message, forKey: message.id)
+                }
+            }
+        }
+    }
+
+    // MARK: - Agents
+
+    public func agent(named name: String) -> Agent? {
+        agents.values.first { $0.participant.attributes["lk.agent_name"] == name || $0.participant.identity?.stringValue == name }
+    }
+
+    public subscript(name: String) -> Agent? {
+        agent(named: name)
+    }
+
+    // MARK: - Lifecycle
+
+    public func start(preConnectAudio: Bool = true, waitForAgent: TimeInterval = 20, options: ConnectOptions? = nil, roomOptions: RoomOptions? = nil) async {
+        guard connectionState == .disconnected else { return }
+
+        error = nil
+        waitForAgentTask?.cancel()
+
+        defer {
+            waitForAgentTask = Task {
+                try await Task.sleep(for: .seconds(waitForAgent))
+                try Task.checkCancellation()
+                if connectionState == .connected, agents.isEmpty {
+                    await end()
+                    self.error = .agentNotConnected
+                }
+            }
+        }
+
+        do {
+            if preConnectAudio {
+                try await room.withPreConnectAudio(timeout: waitForAgent) {
+                    await MainActor.run { self.isListening = true }
+                    try await self.room.connect(credentialsProvider: self.credentials, connectOptions: options, roomOptions: roomOptions)
+                    await MainActor.run { self.isListening = false }
+                }
+            } else {
+                try await room.connect(credentialsProvider: credentials, connectOptions: options, roomOptions: roomOptions)
+            }
+        } catch {
+            self.error = .failedToConnect(error)
+        }
+    }
+
+    public func end() async {
+        await room.disconnect()
+    }
+
+    public func resetError() {
+        error = nil
+    }
+
+    // MARK: - Messages
+
+    @discardableResult
+    public func send(text: String) async -> SentMessage {
+        let message = SentMessage(id: UUID().uuidString, timestamp: Date(), content: .userInput(text))
+        do {
+            for sender in senders {
+                try await sender.send(message)
+            }
+        } catch {
+            self.error = .failedToSend(error)
+        }
+        return message
+    }
+
+    public func getMessageHistory() -> [ReceivedMessage] {
+        messages.values.elements
+    }
+
+    public func restoreMessageHistory(_ messages: [ReceivedMessage]) {
+        self.messages = .init(uniqueKeysWithValues: messages.sorted(by: { $0.timestamp < $1.timestamp }).map { ($0.id, $0) })
+    }
+}
diff --git a/Sources/LiveKit/Agent/LocalMedia.swift b/Sources/LiveKit/Agent/LocalMedia.swift
new file mode 100644
index 000000000..201395c86
--- /dev/null
+++ b/Sources/LiveKit/Agent/LocalMedia.swift
@@ -0,0 +1,165 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+@preconcurrency import AVFoundation
+import LiveKit
+
+@MainActor
+open class LocalMedia: ObservableObject {
+    // MARK: - Error
+
+    public enum Error: LocalizedError {
+        case mediaDevice(Swift.Error)
+    }
+
+    // MARK: - Devices
+
+    @Published public private(set) var error: Error?
+
+    @Published public private(set) var microphoneTrack: (any AudioTrack)?
+    @Published public private(set) var cameraTrack: (any VideoTrack)?
+    @Published public private(set) var screenShareTrack: (any VideoTrack)?
+
+    public var isMicrophoneEnabled: Bool { microphoneTrack != nil }
+    public var isCameraEnabled: Bool { cameraTrack != nil }
+    public var isScreenShareEnabled: Bool { screenShareTrack != nil }
+
+    @Published public private(set) var audioDevices: [AudioDevice] = AudioManager.shared.inputDevices
+    @Published public private(set) var selectedAudioDeviceID: String = AudioManager.shared.inputDevice.deviceId
+
+    @Published public private(set) var videoDevices: [AVCaptureDevice] = []
+    @Published public private(set) var selectedVideoDeviceID: String?
+
+    @Published public private(set) var canSwitchCamera = false
+
+    // MARK: - Dependencies
+
+    private var room: Room
+
+    // MARK: - Initialization
+
+    public init(room: Room) {
+        self.room = room
+
+        observe(room: room)
+        observeDevices()
+    }
+
+    public convenience init(conversation: Conversation) {
+        self.init(room: conversation.room)
+    }
+
+    private func observe(room: Room) {
+        Task { [weak self] in
+            for await _ in room.changes {
+                guard let self else { return }
+
+                microphoneTrack = room.localParticipant.firstAudioTrack
+                cameraTrack = room.localParticipant.firstCameraVideoTrack
+                screenShareTrack = room.localParticipant.firstScreenShareVideoTrack
+            }
+        }
+    }
+
+    private func observeDevices() {
+        try? AudioManager.shared.set(microphoneMuteMode: .inputMixer) // don't play mute sound effect
+        Task {
+            try await AudioManager.shared.setRecordingAlwaysPreparedMode(true)
+        }
+
+        AudioManager.shared.onDeviceUpdate = { [weak self] _ in
+            Task { @MainActor in
+                self?.audioDevices = AudioManager.shared.inputDevices
+                self?.selectedAudioDeviceID = AudioManager.shared.defaultInputDevice.deviceId
+            }
+        }
+
+        Task {
+            canSwitchCamera = try await CameraCapturer.canSwitchPosition()
+            videoDevices = try await CameraCapturer.captureDevices()
+            selectedVideoDeviceID = videoDevices.first?.uniqueID
+        }
+    }
+
+    deinit {
+        AudioManager.shared.onDeviceUpdate = nil
+    }
+
+    // MARK: - Toggle
+
+    public func toggleMicrophone() async {
+        do {
+            try await room.localParticipant.setMicrophone(enabled: !isMicrophoneEnabled)
+        } catch {
+            self.error = .mediaDevice(error)
+        }
+    }
+
+    public func toggleCamera(disableScreenShare: Bool = false) async {
+        let enable = !isCameraEnabled
+        do {
+            if enable, disableScreenShare, isScreenShareEnabled {
+                try await room.localParticipant.setScreenShare(enabled: false)
+            }
+
+            let device = try await CameraCapturer.captureDevices().first(where: { $0.uniqueID == selectedVideoDeviceID })
+            try await room.localParticipant.setCamera(enabled: enable, captureOptions: CameraCaptureOptions(device: device))
+        } catch {
+            self.error = .mediaDevice(error)
+        }
+    }
+
+    public func toggleScreenShare(disableCamera: Bool = false) async {
+        let enable = !isScreenShareEnabled
+        do {
+            if enable, disableCamera, isCameraEnabled {
+                try await room.localParticipant.setCamera(enabled: false)
+            }
+            try await room.localParticipant.setScreenShare(enabled: enable)
+        } catch {
+            self.error = .mediaDevice(error)
+        }
+    }
+
+    // MARK: - Select
+
+    public func select(audioDevice: AudioDevice) {
+        selectedAudioDeviceID = audioDevice.deviceId
+
+        let device = AudioManager.shared.inputDevices.first(where: { $0.deviceId == selectedAudioDeviceID }) ?? AudioManager.shared.defaultInputDevice
+        AudioManager.shared.inputDevice = device
+    }
+
+    public func select(videoDevice: AVCaptureDevice) async {
+        selectedVideoDeviceID = videoDevice.uniqueID
+
+        guard let cameraCapturer = getCameraCapturer() else { return }
+        let captureOptions = CameraCaptureOptions(device: videoDevice)
+        _ = try? await cameraCapturer.set(options: captureOptions)
+    }
+
+    public func switchCamera() async {
+        guard let cameraCapturer = getCameraCapturer() else { return }
+        _ = try? await cameraCapturer.switchCameraPosition()
+    }
+
+    // MARK: - Private
+
+    private func getCameraCapturer() -> CameraCapturer? {
+        guard let cameraTrack = room.localParticipant.firstCameraVideoTrack as? LocalVideoTrack else { return nil }
+        return cameraTrack.capturer as? CameraCapturer
+    }
+}
diff --git a/Sources/LiveKit/Support/ObservableObject+.swift b/Sources/LiveKit/Support/ObservableObject+.swift
new file mode 100644
index 000000000..863d345e0
--- /dev/null
+++ b/Sources/LiveKit/Support/ObservableObject+.swift
@@ -0,0 +1,34 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Combine
+
+@available(iOS 15, *)
+extension ObservableObject {
+    typealias BufferedObjectWillChangePublisher = Publishers.Buffer<ObjectWillChangePublisher>
+
+    // This is necessary due to ObservableObjectPublisher not respecting the demand.
+    // See: https://forums.swift.org/t/asyncpublisher-causes-crash-in-rather-simple-situation
+    private var bufferedObjectWillChange: BufferedObjectWillChangePublisher {
+        objectWillChange
+            .buffer(size: 1, prefetch: .byRequest, whenFull: .dropOldest)
+    }
+
+    /// A publisher that emits the `objectWillChange` events.
+    var changes: AsyncPublisher<BufferedObjectWillChangePublisher> {
+        bufferedObjectWillChange.values
+    }
+}

From f1dc53c41e04167b745ef80dbec48dfa2d1c51da Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Thu, 18 Sep 2025 13:40:13 +0200
Subject: [PATCH 22/28] Fix inconsistencies

---
 Sources/LiveKit/Agent/Agent.swift             |  9 +++--
 Sources/LiveKit/Agent/AgentState+.swift       | 21 ------------
 .../TranscriptionDelegateReceiver.swift       |  1 -
 .../Receive/TranscriptionStreamReceiver.swift |  1 -
 .../Agent/Chat/Send/TextMessageSender.swift   |  1 -
 .../Agent/Conversation+Environment.swift      | 33 ++++++++++++++-----
 Sources/LiveKit/Agent/Conversation.swift      |  7 ++--
 Sources/LiveKit/Agent/LocalMedia.swift        |  3 +-
 .../LiveKit/Support/ObservableObject+.swift   | 31 +++++++++--------
 Sources/LiveKit/Track/VideoTrack.swift        |  8 +++++
 10 files changed, 61 insertions(+), 54 deletions(-)
 delete mode 100644 Sources/LiveKit/Agent/AgentState+.swift

diff --git a/Sources/LiveKit/Agent/Agent.swift b/Sources/LiveKit/Agent/Agent.swift
index 70457f252..f2a23bf0b 100644
--- a/Sources/LiveKit/Agent/Agent.swift
+++ b/Sources/LiveKit/Agent/Agent.swift
@@ -15,7 +15,6 @@
  */
 
 import Foundation
-import LiveKit
 
 @MainActor
 open class Agent: ObservableObject {
@@ -33,7 +32,7 @@ open class Agent: ObservableObject {
 
     private func observe(_ participant: Participant) {
         Task { [weak self] in
-            for await _ in participant.changes {
+            for try await _ in participant.changes {
                 guard let self else { return }
 
                 state = participant.agentState
@@ -47,3 +46,9 @@ open class Agent: ObservableObject {
         avatarVideoTrack = participant.avatarWorker?.firstCameraVideoTrack
     }
 }
+
+extension AgentState: CustomStringConvertible {
+    public var description: String {
+        rawValue.capitalized
+    }
+}
diff --git a/Sources/LiveKit/Agent/AgentState+.swift b/Sources/LiveKit/Agent/AgentState+.swift
deleted file mode 100644
index 9bb45b096..000000000
--- a/Sources/LiveKit/Agent/AgentState+.swift
+++ /dev/null
@@ -1,21 +0,0 @@
-/*
- * Copyright 2025 LiveKit
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-extension AgentState: CustomStringConvertible {
-    public var description: String {
-        rawValue.capitalized
-    }
-}
diff --git a/Sources/LiveKit/Agent/Chat/Receive/TranscriptionDelegateReceiver.swift b/Sources/LiveKit/Agent/Chat/Receive/TranscriptionDelegateReceiver.swift
index 824d29a03..43c8bfe1a 100644
--- a/Sources/LiveKit/Agent/Chat/Receive/TranscriptionDelegateReceiver.swift
+++ b/Sources/LiveKit/Agent/Chat/Receive/TranscriptionDelegateReceiver.swift
@@ -15,7 +15,6 @@
  */
 
 import Foundation
-import LiveKit
 
 /// An actor that receives transcription messages from the room and yields them as messages.
 ///
diff --git a/Sources/LiveKit/Agent/Chat/Receive/TranscriptionStreamReceiver.swift b/Sources/LiveKit/Agent/Chat/Receive/TranscriptionStreamReceiver.swift
index 9ac2a1ce1..40a541ec5 100644
--- a/Sources/LiveKit/Agent/Chat/Receive/TranscriptionStreamReceiver.swift
+++ b/Sources/LiveKit/Agent/Chat/Receive/TranscriptionStreamReceiver.swift
@@ -15,7 +15,6 @@
  */
 
 import Foundation
-import LiveKit
 
 /// An actor that converts raw text streams from the LiveKit `Room` into `Message` objects.
 /// - Note: Streams are supported by `livekit-agents` >= 1.0.0.
diff --git a/Sources/LiveKit/Agent/Chat/Send/TextMessageSender.swift b/Sources/LiveKit/Agent/Chat/Send/TextMessageSender.swift
index af4bc6fb1..3fcfc87e0 100644
--- a/Sources/LiveKit/Agent/Chat/Send/TextMessageSender.swift
+++ b/Sources/LiveKit/Agent/Chat/Send/TextMessageSender.swift
@@ -15,7 +15,6 @@
  */
 
 import Foundation
-import LiveKit
 
 /// An actor that sends local messages to the agent.
 /// Currently, it only supports sending text messages.
diff --git a/Sources/LiveKit/Agent/Conversation+Environment.swift b/Sources/LiveKit/Agent/Conversation+Environment.swift
index e2feba7c3..23ddb4f53 100644
--- a/Sources/LiveKit/Agent/Conversation+Environment.swift
+++ b/Sources/LiveKit/Agent/Conversation+Environment.swift
@@ -16,43 +16,60 @@
 
 import SwiftUI
 
-extension EnvironmentValues {
+#if swift(>=6.0)
+public extension EnvironmentValues {
     @Entry var agentName: String? = nil
 }
+#else
+public struct AgentNameKey: EnvironmentKey {
+    public static let defaultValue: String? = nil
+}
+
+public extension EnvironmentValues {
+    var agentName: String? {
+        get { self[AgentNameKey.self] }
+        set { self[AgentNameKey.self] = newValue }
+    }
+}
+#endif
 
 @MainActor
 @propertyWrapper
-struct LKConversation: DynamicProperty {
+public struct LKConversation: DynamicProperty {
     @EnvironmentObject private var conversation: Conversation
 
-    var wrappedValue: Conversation {
+    public init() {}
+
+    public var wrappedValue: Conversation {
         conversation
     }
 }
 
 @MainActor
 @propertyWrapper
-struct LKLocalMedia: DynamicProperty {
+public struct LKLocalMedia: DynamicProperty {
     @EnvironmentObject private var localMedia: LocalMedia
 
-    var wrappedValue: LocalMedia {
+    public init() {}
+
+    public var wrappedValue: LocalMedia {
         localMedia
     }
 }
 
 @MainActor
 @propertyWrapper
-struct LKAgent: DynamicProperty {
+public struct LKAgent: DynamicProperty {
     @EnvironmentObject private var conversation: Conversation
     @Environment(\.agentName) private var environmentName
 
     let agentName: String?
 
-    init(named agentName: String? = nil) {
+    public init(named agentName: String? = nil) {
         self.agentName = agentName
     }
 
-    var wrappedValue: Agent? {
+    public var wrappedValue: Agent? {
         if let agentName {
             return conversation.agent(named: agentName)
         } else if let environmentName {
diff --git a/Sources/LiveKit/Agent/Conversation.swift b/Sources/LiveKit/Agent/Conversation.swift
index 8edef675b..4cb2b452f 100644
--- a/Sources/LiveKit/Agent/Conversation.swift
+++ b/Sources/LiveKit/Agent/Conversation.swift
@@ -14,9 +14,8 @@
  * limitations under the License.
  */
 
-import Collections
 import Foundation
-import LiveKit
+import OrderedCollections
 
 @MainActor
 open class Conversation: ObservableObject {
@@ -86,7 +85,7 @@ open class Conversation: ObservableObject {
 
     private func observe(room: Room, agentName _: String?) {
         Task { [weak self] in
-            for await _ in room.changes {
+            for try await _ in room.changes {
                 guard let self else { return }
 
                 connectionState = room.connectionState
@@ -143,7 +142,7 @@ open class Conversation: ObservableObject {
 
         defer {
             waitForAgentTask = Task {
-                try await Task.sleep(for: .seconds(waitForAgent))
+                try await Task.sleep(nanoseconds: UInt64(TimeInterval(NSEC_PER_SEC) * waitForAgent))
                 try Task.checkCancellation()
                 if connectionState == .connected, agents.isEmpty {
                     await end()
diff --git a/Sources/LiveKit/Agent/LocalMedia.swift b/Sources/LiveKit/Agent/LocalMedia.swift
index 201395c86..b3f4c6de9 100644
--- a/Sources/LiveKit/Agent/LocalMedia.swift
+++ b/Sources/LiveKit/Agent/LocalMedia.swift
@@ -15,7 +15,6 @@
  */
 
 @preconcurrency import AVFoundation
-import LiveKit
 
 @MainActor
 open class LocalMedia: ObservableObject {
@@ -64,7 +63,7 @@ open class LocalMedia: ObservableObject {
 
     private func observe(room: Room) {
         Task { [weak self] in
-            for await _ in room.changes {
+            for try await _ in room.changes {
                 guard let self else { return }
 
                 microphoneTrack = room.localParticipant.firstAudioTrack
diff --git a/Sources/LiveKit/Support/ObservableObject+.swift b/Sources/LiveKit/Support/ObservableObject+.swift
index 863d345e0..68a3d7a18 100644
--- a/Sources/LiveKit/Support/ObservableObject+.swift
+++ b/Sources/LiveKit/Support/ObservableObject+.swift
@@ -14,21 +14,24 @@
  * limitations under the License.
  */
 
-import Combine
+@preconcurrency import Combine
 
-@available(iOS 15, *)
 extension ObservableObject {
-    typealias BufferedObjectWillChangePublisher = Publishers.Buffer<ObjectWillChangePublisher>
-
-    // This is necessary due to ObservableObjectPublisher not respecting the demand.
-    // See: https://forums.swift.org/t/asyncpublisher-causes-crash-in-rather-simple-situation
-    private var bufferedObjectWillChange: BufferedObjectWillChangePublisher {
-        objectWillChange
-            .buffer(size: 1, prefetch: .byRequest, whenFull: .dropOldest)
-    }
-
-    /// A publisher that emits the `objectWillChange` events.
-    var changes: AsyncPublisher<BufferedObjectWillChangePublisher> {
-        bufferedObjectWillChange.values
+    /// An async sequence that emits the `objectWillChange` events.
+    var changes: any AsyncSequence {
+        if #available(macOS 12.0, iOS 15.0, tvOS 15.0, *) {
+            // This is necessary due to ObservableObjectPublisher not respecting the demand.
+            // See: https://forums.swift.org/t/asyncpublisher-causes-crash-in-rather-simple-situation
+            objectWillChange.buffer(size: 1, prefetch: .byRequest, whenFull: .dropOldest).values
+        } else {
+            AsyncStream { continuation in
+                let cancellable = objectWillChange.sink { _ in
+                    continuation.yield()
+                }
+                continuation.onTermination = { _ in
+                    cancellable.cancel()
+                }
+            }
+        }
     }
 }
diff --git a/Sources/LiveKit/Track/VideoTrack.swift b/Sources/LiveKit/Track/VideoTrack.swift
index 07bd636f3..49bf94520 100644
--- a/Sources/LiveKit/Track/VideoTrack.swift
+++ b/Sources/LiveKit/Track/VideoTrack.swift
@@ -69,3 +69,11 @@ extension VideoTrack {
         return missingCodecs
     }
 }
+
+public extension VideoTrack {
+    /// The aspect ratio of the video track or 1 if the dimensions are not available.
+    var aspectRatio: CGFloat {
+        guard let dimensions else { return 1 }
+        return CGFloat(dimensions.width) / CGFloat(dimensions.height)
+    }
+}

From cd27f1db851f677f32d7c867cdf43a941451222e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Thu, 18 Sep 2025 15:31:33 +0200
Subject: [PATCH 23/28] Media state from participant

---
 Sources/LiveKit/Agent/LocalMedia.swift | 44 +++++++++++++++-----------
 1 file changed, 26 insertions(+), 18 deletions(-)

diff --git a/Sources/LiveKit/Agent/LocalMedia.swift b/Sources/LiveKit/Agent/LocalMedia.swift
index b3f4c6de9..e0d7775ab 100644
--- a/Sources/LiveKit/Agent/LocalMedia.swift
+++ b/Sources/LiveKit/Agent/LocalMedia.swift
@@ -32,9 +32,9 @@ open class LocalMedia: ObservableObject {
     @Published public private(set) var cameraTrack: (any VideoTrack)?
     @Published public private(set) var screenShareTrack: (any VideoTrack)?
 
-    public var isMicrophoneEnabled: Bool { microphoneTrack != nil }
-    public var isCameraEnabled: Bool { cameraTrack != nil }
-    public var isScreenShareEnabled: Bool { screenShareTrack != nil }
+    @Published public private(set) var isMicrophoneEnabled: Bool = false
+    @Published public private(set) var isCameraEnabled: Bool = false
+    @Published public private(set) var isScreenShareEnabled: Bool = false
 
     @Published public private(set) var audioDevices: [AudioDevice] = AudioManager.shared.inputDevices
     @Published public private(set) var selectedAudioDeviceID: String = AudioManager.shared.inputDevice.deviceId
@@ -46,29 +46,37 @@ open class LocalMedia: ObservableObject {
 
     // MARK: - Dependencies
 
-    private var room: Room
+    private var localParticipant: LocalParticipant
 
     // MARK: - Initialization
 
-    public init(room: Room) {
-        self.room = room
+    public init(localParticipant: LocalParticipant) {
+        self.localParticipant = localParticipant
 
-        observe(room: room)
+        observe(localParticipant)
         observeDevices()
     }
 
+    public convenience init(room: Room) {
+        self.init(localParticipant: room.localParticipant)
+    }
+
     public convenience init(conversation: Conversation) {
         self.init(room: conversation.room)
     }
 
-    private func observe(room: Room) {
+    private func observe(_ localParticipant: LocalParticipant) {
         Task { [weak self] in
-            for try await _ in room.changes {
+            for try await _ in localParticipant.changes {
                 guard let self else { return }
 
-                microphoneTrack = room.localParticipant.firstAudioTrack
-                cameraTrack = room.localParticipant.firstCameraVideoTrack
-                screenShareTrack = room.localParticipant.firstScreenShareVideoTrack
+                microphoneTrack = localParticipant.firstAudioTrack
+                cameraTrack = localParticipant.firstCameraVideoTrack
+                screenShareTrack = localParticipant.firstScreenShareVideoTrack
+
+                isMicrophoneEnabled = localParticipant.isMicrophoneEnabled()
+                isCameraEnabled = localParticipant.isCameraEnabled()
+                isScreenShareEnabled = localParticipant.isScreenShareEnabled()
             }
         }
     }
@@ -101,7 +109,7 @@ open class LocalMedia: ObservableObject {
 
     public func toggleMicrophone() async {
         do {
-            try await room.localParticipant.setMicrophone(enabled: !isMicrophoneEnabled)
+            try await localParticipant.setMicrophone(enabled: !isMicrophoneEnabled)
         } catch {
             self.error = .mediaDevice(error)
         }
@@ -111,11 +119,11 @@ open class LocalMedia: ObservableObject {
         let enable = !isCameraEnabled
         do {
             if enable, disableScreenShare, isScreenShareEnabled {
-                try await room.localParticipant.setScreenShare(enabled: false)
+                try await localParticipant.setScreenShare(enabled: false)
             }
 
             let device = try await CameraCapturer.captureDevices().first(where: { $0.uniqueID == selectedVideoDeviceID })
-            try await room.localParticipant.setCamera(enabled: enable, captureOptions: CameraCaptureOptions(device: device))
+            try await localParticipant.setCamera(enabled: enable, captureOptions: CameraCaptureOptions(device: device))
         } catch {
             self.error = .mediaDevice(error)
         }
@@ -125,9 +133,9 @@ open class LocalMedia: ObservableObject {
         let enable = !isScreenShareEnabled
         do {
             if enable, disableCamera, isCameraEnabled {
-                try await room.localParticipant.setCamera(enabled: false)
+                try await localParticipant.setCamera(enabled: false)
             }
-            try await room.localParticipant.setScreenShare(enabled: enable)
+            try await localParticipant.setScreenShare(enabled: enable)
         } catch {
             self.error = .mediaDevice(error)
         }
@@ -158,7 +166,7 @@ open class LocalMedia: ObservableObject {
     // MARK: - Private
 
     private func getCameraCapturer() -> CameraCapturer? {
-        guard let cameraTrack = room.localParticipant.firstCameraVideoTrack as? LocalVideoTrack else { return nil }
+        guard let cameraTrack = localParticipant.firstCameraVideoTrack as? LocalVideoTrack else { return nil }
         return cameraTrack.capturer as? CameraCapturer
     }
 }

From 100abcd7c0abbcc58fc2a9768e780d719aaa99ed Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Fri, 19 Sep 2025 13:37:08 +0200
Subject: [PATCH 24/28] Naming

---
 Sources/LiveKit/Agent/Conversation+Environment.swift | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Sources/LiveKit/Agent/Conversation+Environment.swift b/Sources/LiveKit/Agent/Conversation+Environment.swift
index 23ddb4f53..d0f64cde7 100644
--- a/Sources/LiveKit/Agent/Conversation+Environment.swift
+++ b/Sources/LiveKit/Agent/Conversation+Environment.swift
@@ -35,7 +35,7 @@ public extension EnvironmentValues {
 
 @MainActor
 @propertyWrapper
-public struct LKConversation: DynamicProperty {
+public struct LiveKitConversation: DynamicProperty {
     @EnvironmentObject private var conversation: Conversation
 
     public init() {}
@@ -47,7 +47,7 @@ public struct LKConversation: DynamicProperty {
 
 @MainActor
 @propertyWrapper
-public struct LKLocalMedia: DynamicProperty {
+public struct LiveKitLocalMedia: DynamicProperty {
     @EnvironmentObject private var localMedia: LocalMedia
 
     public init() {}
@@ -59,13 +59,13 @@ public struct LKLocalMedia: DynamicProperty {
 
 @MainActor
 @propertyWrapper
-public struct LKAgent: DynamicProperty {
+public struct LiveKitAgent: DynamicProperty {
     @EnvironmentObject private var conversation: Conversation
     @Environment(\.agentName) private var environmentName
 
     let agentName: String?
 
-    public init(named agentName: String? = nil) {
+    public init(_ agentName: String? = nil) {
         self.agentName = agentName
     }
 

From a4ab04c8466436ff1478c18c9e4b3ad72b902805 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Tue, 23 Sep 2025 10:21:41 +0200
Subject: [PATCH 25/28] Attributes gen

---
 .../Receive/TranscriptionStreamReceiver.swift | 25 ++++++++--------
 .../Types/Attributes/AttributeTypings.swift   | 29 +++++++++++++++++++
 2 files changed, 42 insertions(+), 12 deletions(-)

diff --git a/Sources/LiveKit/Agent/Chat/Receive/TranscriptionStreamReceiver.swift b/Sources/LiveKit/Agent/Chat/Receive/TranscriptionStreamReceiver.swift
index 40a541ec5..758ce5043 100644
--- a/Sources/LiveKit/Agent/Chat/Receive/TranscriptionStreamReceiver.swift
+++ b/Sources/LiveKit/Agent/Chat/Receive/TranscriptionStreamReceiver.swift
@@ -54,7 +54,7 @@ import Foundation
 /// Message(id: "4", timestamp: 2025-01-01 12:00:30 +0000, content: .userTranscript("Hello Apple!"))
 /// ```
 ///
-actor TranscriptionStreamReceiver: MessageReceiver {
+actor TranscriptionStreamReceiver: MessageReceiver, Loggable {
     private struct PartialMessageID: Hashable {
         let segmentID: String
         let participantID: Participant.Identity
@@ -75,25 +75,21 @@ actor TranscriptionStreamReceiver: MessageReceiver {
         }
     }
 
-    private let transcriptionTopic = "lk.transcription"
-    private enum TranscriptionAttributes: String {
-        case final = "lk.transcription_final"
-        case segment = "lk.segment_id"
-    }
-
     private let room: Room
+    private let topic: String
 
     private lazy var partialMessages: [PartialMessageID: PartialMessage] = [:]
 
-    init(room: Room) {
+    init(room: Room, topic: String = "lk.transcription") {
         self.room = room
+        self.topic = topic
     }
 
     /// Creates a new message stream for the chat topic.
     func messages() async throws -> AsyncStream<ReceivedMessage> {
         let (stream, continuation) = AsyncStream.makeStream(of: ReceivedMessage.self)
 
-        try await room.registerTextStreamHandler(for: transcriptionTopic) { [weak self] reader, participantIdentity in
+        try await room.registerTextStreamHandler(for: topic) { [weak self] reader, participantIdentity in
             guard let self else { return }
             for try await message in reader where !message.isEmpty {
                 await continuation.yield(processIncoming(partialMessage: message, reader: reader, participantIdentity: participantIdentity))
@@ -103,7 +99,7 @@ actor TranscriptionStreamReceiver: MessageReceiver {
         continuation.onTermination = { [weak self] _ in
             Task {
                 guard let self else { return }
-                await self.room.unregisterTextStreamHandler(for: self.transcriptionTopic)
+                await self.room.unregisterTextStreamHandler(for: self.topic)
             }
         }
 
@@ -113,7 +109,12 @@ actor TranscriptionStreamReceiver: MessageReceiver {
     /// Aggregates the incoming text into a message, storing the partial content in the `partialMessages` dictionary.
     /// - Note: When the message is finalized, or a new message is started, the dictionary is purged to limit memory usage.
     private func processIncoming(partialMessage message: String, reader: TextStreamReader, participantIdentity: Participant.Identity) -> ReceivedMessage {
-        let segmentID = reader.info.attributes[TranscriptionAttributes.segment.rawValue] ?? reader.info.id
+        let attributes = reader.info.attributes.mapped(to: TranscriptionAttributes.self)
+        if attributes == nil {
+            log("Unable to read message attributes from \(reader.info.attributes)", .error)
+        }
+
+        let segmentID = attributes?.lkSegmentID ?? reader.info.id
         let participantID = participantIdentity
         let partialID = PartialMessageID(segmentID: segmentID, participantID: participantID)
 
@@ -146,7 +147,7 @@ actor TranscriptionStreamReceiver: MessageReceiver {
             cleanupPreviousTurn(participantIdentity, exceptSegmentID: segmentID)
         }
 
-        let isFinal = reader.info.attributes[TranscriptionAttributes.final.rawValue] == "true"
+        let isFinal = attributes?.lkTranscriptionFinal ?? false
         if isFinal {
             partialMessages[partialID] = nil
         }
diff --git a/Sources/LiveKit/Types/Attributes/AttributeTypings.swift b/Sources/LiveKit/Types/Attributes/AttributeTypings.swift
index 35dbc8f0b..9fc56e609 100644
--- a/Sources/LiveKit/Types/Attributes/AttributeTypings.swift
+++ b/Sources/LiveKit/Types/Attributes/AttributeTypings.swift
@@ -20,6 +20,35 @@ import Foundation
 extension AgentAttributes: Hashable {}
 extension AgentAttributes: Equatable {}
 
+// Bool as String encoding
+extension TranscriptionAttributes {
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        lkSegmentID = try container.decodeIfPresent(String.self, forKey: .lkSegmentID)
+        lkTranscribedTrackID = try container.decodeIfPresent(String.self, forKey: .lkTranscribedTrackID)
+
+        // Decode as Bool first, fallback to String
+        if let boolValue = try? container.decodeIfPresent(Bool.self, forKey: .lkTranscriptionFinal) {
+            lkTranscriptionFinal = boolValue
+        } else if let stringValue = try? container.decodeIfPresent(String.self, forKey: .lkTranscriptionFinal) {
+            lkTranscriptionFinal = (stringValue as NSString).boolValue
+        } else {
+            lkTranscriptionFinal = nil
+        }
+    }
+
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encodeIfPresent(lkSegmentID, forKey: .lkSegmentID)
+        try container.encodeIfPresent(lkTranscribedTrackID, forKey: .lkTranscribedTrackID)
+
+        // Always encode Bool as a string if it exists
+        if let boolValue = lkTranscriptionFinal {
+            try container.encode(boolValue ? "true" : "false", forKey: .lkTranscriptionFinal)
+        }
+    }
+}
+
 // MARK: - AgentAttributes
 
 struct AgentAttributes: Codable, Sendable {

From 1ea3f567aac2feabd2dd99e0e57118df11d10024 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Tue, 23 Sep 2025 12:58:53 +0200
Subject: [PATCH 26/28] Transcription tests

---
 .../Agent/TranscriptionTests.swift            | 196 ++++++++++++++++++
 1 file changed, 196 insertions(+)
 create mode 100644 Tests/LiveKitTests/Agent/TranscriptionTests.swift

diff --git a/Tests/LiveKitTests/Agent/TranscriptionTests.swift b/Tests/LiveKitTests/Agent/TranscriptionTests.swift
new file mode 100644
index 000000000..921caccc9
--- /dev/null
+++ b/Tests/LiveKitTests/Agent/TranscriptionTests.swift
@@ -0,0 +1,196 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+@testable import LiveKit
+import OrderedCollections
+import XCTest
+
+actor MessageCollector {
+    private var updates: [ReceivedMessage] = []
+    private var messages: OrderedDictionary<ReceivedMessage.ID, ReceivedMessage> = [:]
+
+    func add(_ message: ReceivedMessage) {
+        updates.append(message)
+        messages[message.id] = message
+    }
+
+    func getUpdates() -> [ReceivedMessage] {
+        updates
+    }
+
+    func getMessages() -> OrderedDictionary<ReceivedMessage.ID, ReceivedMessage> {
+        messages
+    }
+}
+
+class TranscriptionTests: LKTestCase, @unchecked Sendable {
+    // Same segment, same stream
+    func testUpdates() async throws {
+        let messageExpectation = expectation(description: "Receives all message updates")
+        messageExpectation.expectedFulfillmentCount = 3
+
+        let segmentID = "test-segment"
+        let topic = "lk.transcription"
+
+        let testChunks = ["Hey", " there!", " What's up?"]
+
+        try await withRooms([
+            RoomTestingOptions(canSubscribe: true),
+            RoomTestingOptions(canPublishData: true),
+        ]) { rooms in
+            let receiverRoom = rooms[0]
+            let senderRoom = rooms[1]
+
+            let receiver = TranscriptionStreamReceiver(room: receiverRoom)
+            let messageStream = try await receiver.messages()
+            let streamID = UUID().uuidString
+
+            let messageCollector = MessageCollector()
+
+            let collectionTask = Task { @Sendable in
+                var iterator = messageStream.makeAsyncIterator()
+                while let message = await iterator.next() {
+                    await messageCollector.add(message)
+                    messageExpectation.fulfill()
+                }
+            }
+
+            for (index, chunk) in testChunks.enumerated() {
+                let isLast = index == testChunks.count - 1
+
+                var attributes: [String: String] = [
+                    "lk.segment_id": segmentID,
+                    "lk.transcription_final": "false",
+                ]
+
+                if isLast {
+                    attributes["lk.transcription_final"] = "true"
+                }
+
+                let options = StreamTextOptions(
+                    topic: topic,
+                    attributes: attributes,
+                    id: streamID
+                )
+
+                try await senderRoom.localParticipant.sendText(chunk, options: options)
+                try await Task.sleep(nanoseconds: 10_000_000)
+            }
+
+            await self.fulfillment(of: [messageExpectation], timeout: 5)
+            collectionTask.cancel()
+
+            let updates = await messageCollector.getUpdates()
+            XCTAssertEqual(updates.count, 3)
+            XCTAssertEqual(updates[0].content, .agentTranscript("Hey"))
+            XCTAssertEqual(updates[1].content, .agentTranscript("Hey there!"))
+            XCTAssertEqual(updates[2].content, .agentTranscript("Hey there! What's up?"))
+
+            XCTAssertEqual(updates[0].id, segmentID)
+            XCTAssertEqual(updates[1].id, segmentID)
+            XCTAssertEqual(updates[2].id, segmentID)
+
+            let firstTimestamp = updates[0].timestamp
+            XCTAssertEqual(updates[1].timestamp, firstTimestamp)
+            XCTAssertEqual(updates[2].timestamp, firstTimestamp)
+
+            let messages = await messageCollector.getMessages()
+            XCTAssertEqual(messages.count, 1)
+            XCTAssertEqual(messages.keys[0], segmentID)
+            XCTAssertEqual(messages.values[0].content, .agentTranscript("Hey there! What's up?"))
+            XCTAssertEqual(messages.values[0].id, segmentID)
+            XCTAssertEqual(messages.values[0].timestamp, firstTimestamp)
+        }
+    }
+
+    // Same segment, different stream
+    func testReplace() async throws {
+        let messageExpectation = expectation(description: "Receives all message updates")
+        messageExpectation.expectedFulfillmentCount = 3
+
+        let segmentID = "test-segment"
+        let topic = "lk.transcription"
+
+        let testChunks = ["Hey", "Hey there!", "Hey there! What's up?"]
+
+        try await withRooms([
+            RoomTestingOptions(canSubscribe: true),
+            RoomTestingOptions(canPublishData: true),
+        ]) { rooms in
+            let receiverRoom = rooms[0]
+            let senderRoom = rooms[1]
+
+            let receiver = TranscriptionStreamReceiver(room: receiverRoom)
+            let messageStream = try await receiver.messages()
+
+            let messageCollector = MessageCollector()
+
+            let collectionTask = Task { @Sendable in
+                var iterator = messageStream.makeAsyncIterator()
+                while let message = await iterator.next() {
+                    await messageCollector.add(message)
+                    messageExpectation.fulfill()
+                }
+            }
+
+            for (index, chunk) in testChunks.enumerated() {
+                let isLast = index == testChunks.count - 1
+
+                var attributes: [String: String] = [
+                    "lk.segment_id": segmentID,
+                    "lk.transcription_final": "false",
+                ]
+
+                if isLast {
+                    attributes["lk.transcription_final"] = "true"
+                }
+
+                let options = StreamTextOptions(
+                    topic: topic,
+                    attributes: attributes,
+                    id: UUID().uuidString
+                )
+
+                try await senderRoom.localParticipant.sendText(chunk, options: options)
+                try await Task.sleep(nanoseconds: 10_000_000)
+            }
+
+            await self.fulfillment(of: [messageExpectation], timeout: 5)
+            collectionTask.cancel()
+
+            let updates = await messageCollector.getUpdates()
+            XCTAssertEqual(updates.count, 3)
+            XCTAssertEqual(updates[0].content, .agentTranscript("Hey"))
+            XCTAssertEqual(updates[1].content, .agentTranscript("Hey there!"))
+            XCTAssertEqual(updates[2].content, .agentTranscript("Hey there! What's up?"))
+
+            XCTAssertEqual(updates[0].id, segmentID)
+            XCTAssertEqual(updates[1].id, segmentID)
+            XCTAssertEqual(updates[2].id, segmentID)
+
+            let firstTimestamp = updates[0].timestamp
+            XCTAssertEqual(updates[1].timestamp, firstTimestamp)
+            XCTAssertEqual(updates[2].timestamp, firstTimestamp)
+
+            let messages = await messageCollector.getMessages()
+            XCTAssertEqual(messages.count, 1)
+            XCTAssertEqual(messages.keys[0], segmentID)
+            XCTAssertEqual(messages.values[0].content, .agentTranscript("Hey there! What's up?"))
+            XCTAssertEqual(messages.values[0].id, segmentID)
+            XCTAssertEqual(messages.values[0].timestamp, firstTimestamp)
+        }
+    }
+}

From 212035c709815fedc06db6a51641fe39a2552004 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Tue, 23 Sep 2025 13:21:48 +0200
Subject: [PATCH 27/28] Extract tests

---
 .../Agent/TranscriptionTests.swift            | 247 +++++++++---------
 1 file changed, 118 insertions(+), 129 deletions(-)

diff --git a/Tests/LiveKitTests/Agent/TranscriptionTests.swift b/Tests/LiveKitTests/Agent/TranscriptionTests.swift
index 921caccc9..1090d8532 100644
--- a/Tests/LiveKitTests/Agent/TranscriptionTests.swift
+++ b/Tests/LiveKitTests/Agent/TranscriptionTests.swift
@@ -37,160 +37,149 @@ actor MessageCollector {
 }
 
 class TranscriptionTests: LKTestCase, @unchecked Sendable {
+    private var rooms: [Room] = []
+    private var receiver: TranscriptionStreamReceiver!
+    private var senderRoom: Room!
+    private var messageCollector: MessageCollector!
+    private var collectionTask: Task<Void, Never>!
+    private var messageExpectation: XCTestExpectation!
+
     // Same segment, same stream
     func testUpdates() async throws {
-        let messageExpectation = expectation(description: "Receives all message updates")
-        messageExpectation.expectedFulfillmentCount = 3
-
         let segmentID = "test-segment"
-        let topic = "lk.transcription"
-
+        let streamID = UUID().uuidString
         let testChunks = ["Hey", " there!", " What's up?"]
+        let expectedContent = ["Hey", "Hey there!", "Hey there! What's up?"]
+
+        try await runTranscriptionTest(
+            chunks: testChunks,
+            segmentID: segmentID,
+            streamID: streamID,
+            expectedContent: expectedContent
+        )
+    }
 
-        try await withRooms([
-            RoomTestingOptions(canSubscribe: true),
-            RoomTestingOptions(canPublishData: true),
-        ]) { rooms in
-            let receiverRoom = rooms[0]
-            let senderRoom = rooms[1]
+    // Same segment, different stream
+    func testReplace() async throws {
+        let segmentID = "test-segment"
+        let testChunks = ["Hey", "Hey there!", "Hey there! What's up?"]
+        let expectedContent = ["Hey", "Hey there!", "Hey there! What's up?"]
+
+        try await runTranscriptionTest(
+            chunks: testChunks,
+            segmentID: segmentID,
+            streamID: nil,
+            expectedContent: expectedContent
+        )
+    }
 
-            let receiver = TranscriptionStreamReceiver(room: receiverRoom)
-            let messageStream = try await receiver.messages()
-            let streamID = UUID().uuidString
+    private func setupTestEnvironment(expectedCount: Int) async throws {
+        messageExpectation = expectation(description: "Receives all message updates")
+        messageExpectation.expectedFulfillmentCount = expectedCount
 
-            let messageCollector = MessageCollector()
+        receiver = TranscriptionStreamReceiver(room: rooms[0])
+        let messageStream = try await receiver.messages()
+        messageCollector = MessageCollector()
+        senderRoom = rooms[1]
 
-            let collectionTask = Task { @Sendable in
-                var iterator = messageStream.makeAsyncIterator()
-                while let message = await iterator.next() {
-                    await messageCollector.add(message)
-                    messageExpectation.fulfill()
-                }
+        collectionTask = Task { @Sendable in
+            var iterator = messageStream.makeAsyncIterator()
+            while let message = await iterator.next() {
+                await self.messageCollector.add(message)
+                self.messageExpectation.fulfill()
             }
+        }
+    }
 
-            for (index, chunk) in testChunks.enumerated() {
-                let isLast = index == testChunks.count - 1
-
-                var attributes: [String: String] = [
-                    "lk.segment_id": segmentID,
-                    "lk.transcription_final": "false",
-                ]
+    private func sendTranscriptionChunks(
+        chunks: [String],
+        segmentID: String,
+        streamID: String? = nil,
+        to room: Room
+    ) async throws {
+        let topic = "lk.transcription"
 
-                if isLast {
-                    attributes["lk.transcription_final"] = "true"
-                }
+        for (index, chunk) in chunks.enumerated() {
+            let isLast = index == chunks.count - 1
 
-                let options = StreamTextOptions(
-                    topic: topic,
-                    attributes: attributes,
-                    id: streamID
-                )
+            var attributes: [String: String] = [
+                "lk.segment_id": segmentID,
+                "lk.transcription_final": "false",
+            ]
 
-                try await senderRoom.localParticipant.sendText(chunk, options: options)
-                try await Task.sleep(nanoseconds: 10_000_000)
+            if isLast {
+                attributes["lk.transcription_final"] = "true"
             }
 
-            await self.fulfillment(of: [messageExpectation], timeout: 5)
-            collectionTask.cancel()
-
-            let updates = await messageCollector.getUpdates()
-            XCTAssertEqual(updates.count, 3)
-            XCTAssertEqual(updates[0].content, .agentTranscript("Hey"))
-            XCTAssertEqual(updates[1].content, .agentTranscript("Hey there!"))
-            XCTAssertEqual(updates[2].content, .agentTranscript("Hey there! What's up?"))
-
-            XCTAssertEqual(updates[0].id, segmentID)
-            XCTAssertEqual(updates[1].id, segmentID)
-            XCTAssertEqual(updates[2].id, segmentID)
-
-            let firstTimestamp = updates[0].timestamp
-            XCTAssertEqual(updates[1].timestamp, firstTimestamp)
-            XCTAssertEqual(updates[2].timestamp, firstTimestamp)
-
-            let messages = await messageCollector.getMessages()
-            XCTAssertEqual(messages.count, 1)
-            XCTAssertEqual(messages.keys[0], segmentID)
-            XCTAssertEqual(messages.values[0].content, .agentTranscript("Hey there! What's up?"))
-            XCTAssertEqual(messages.values[0].id, segmentID)
-            XCTAssertEqual(messages.values[0].timestamp, firstTimestamp)
+            let options = StreamTextOptions(
+                topic: topic,
+                attributes: attributes,
+                id: streamID ?? UUID().uuidString
+            )
+
+            try await room.localParticipant.sendText(chunk, options: options)
+            try await Task.sleep(nanoseconds: 10_000_000)
         }
     }
 
-    // Same segment, different stream
-    func testReplace() async throws {
-        let messageExpectation = expectation(description: "Receives all message updates")
-        messageExpectation.expectedFulfillmentCount = 3
+    private func validateTranscriptionResults(
+        updates: [ReceivedMessage],
+        messages: OrderedDictionary<ReceivedMessage.ID, ReceivedMessage>,
+        segmentID: String,
+        expectedContent: [String]
+    ) {
+        // Validate updates
+        XCTAssertEqual(updates.count, expectedContent.count)
+        for (index, expected) in expectedContent.enumerated() {
+            XCTAssertEqual(updates[index].content, .agentTranscript(expected))
+            XCTAssertEqual(updates[index].id, segmentID)
+        }
 
-        let segmentID = "test-segment"
-        let topic = "lk.transcription"
+        // Validate timestamps are consistent
+        let firstTimestamp = updates[0].timestamp
+        for update in updates {
+            XCTAssertEqual(update.timestamp, firstTimestamp)
+        }
 
-        let testChunks = ["Hey", "Hey there!", "Hey there! What's up?"]
+        // Validate final message
+        XCTAssertEqual(messages.count, 1)
+        XCTAssertEqual(messages.keys[0], segmentID)
+        XCTAssertEqual(messages.values[0].content, .agentTranscript(expectedContent.last!))
+        XCTAssertEqual(messages.values[0].id, segmentID)
+        XCTAssertEqual(messages.values[0].timestamp, firstTimestamp)
+    }
 
+    private func runTranscriptionTest(
+        chunks: [String],
+        segmentID: String,
+        streamID: String? = nil,
+        expectedContent: [String]
+    ) async throws {
         try await withRooms([
             RoomTestingOptions(canSubscribe: true),
             RoomTestingOptions(canPublishData: true),
         ]) { rooms in
-            let receiverRoom = rooms[0]
-            let senderRoom = rooms[1]
-
-            let receiver = TranscriptionStreamReceiver(room: receiverRoom)
-            let messageStream = try await receiver.messages()
-
-            let messageCollector = MessageCollector()
-
-            let collectionTask = Task { @Sendable in
-                var iterator = messageStream.makeAsyncIterator()
-                while let message = await iterator.next() {
-                    await messageCollector.add(message)
-                    messageExpectation.fulfill()
-                }
-            }
-
-            for (index, chunk) in testChunks.enumerated() {
-                let isLast = index == testChunks.count - 1
-
-                var attributes: [String: String] = [
-                    "lk.segment_id": segmentID,
-                    "lk.transcription_final": "false",
-                ]
-
-                if isLast {
-                    attributes["lk.transcription_final"] = "true"
-                }
-
-                let options = StreamTextOptions(
-                    topic: topic,
-                    attributes: attributes,
-                    id: UUID().uuidString
-                )
-
-                try await senderRoom.localParticipant.sendText(chunk, options: options)
-                try await Task.sleep(nanoseconds: 10_000_000)
-            }
-
-            await self.fulfillment(of: [messageExpectation], timeout: 5)
-            collectionTask.cancel()
-
-            let updates = await messageCollector.getUpdates()
-            XCTAssertEqual(updates.count, 3)
-            XCTAssertEqual(updates[0].content, .agentTranscript("Hey"))
-            XCTAssertEqual(updates[1].content, .agentTranscript("Hey there!"))
-            XCTAssertEqual(updates[2].content, .agentTranscript("Hey there! What's up?"))
-
-            XCTAssertEqual(updates[0].id, segmentID)
-            XCTAssertEqual(updates[1].id, segmentID)
-            XCTAssertEqual(updates[2].id, segmentID)
-
-            let firstTimestamp = updates[0].timestamp
-            XCTAssertEqual(updates[1].timestamp, firstTimestamp)
-            XCTAssertEqual(updates[2].timestamp, firstTimestamp)
-
-            let messages = await messageCollector.getMessages()
-            XCTAssertEqual(messages.count, 1)
-            XCTAssertEqual(messages.keys[0], segmentID)
-            XCTAssertEqual(messages.values[0].content, .agentTranscript("Hey there! What's up?"))
-            XCTAssertEqual(messages.values[0].id, segmentID)
-            XCTAssertEqual(messages.values[0].timestamp, firstTimestamp)
+            self.rooms = rooms
+            try await self.setupTestEnvironment(expectedCount: expectedContent.count)
+            try await self.sendTranscriptionChunks(
+                chunks: chunks,
+                segmentID: segmentID,
+                streamID: streamID,
+                to: self.senderRoom
+            )
+
+            await self.fulfillment(of: [self.messageExpectation], timeout: 5)
+            self.collectionTask.cancel()
+
+            let updates = await self.messageCollector.getUpdates()
+            let messages = await self.messageCollector.getMessages()
+
+            self.validateTranscriptionResults(
+                updates: updates,
+                messages: messages,
+                segmentID: segmentID,
+                expectedContent: expectedContent
+            )
         }
     }
 }

From c52f944dc6fd9e13479d5f19d22834c235473606 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C5=82az=CC=87ej=20Pankowski?=
 <86720177+pblazej@users.noreply.github.com>
Date: Tue, 23 Sep 2025 14:04:39 +0200
Subject: [PATCH 28/28] Renaming

---
 Sources/LiveKit/Agent/Conversation.swift | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Sources/LiveKit/Agent/Conversation.swift b/Sources/LiveKit/Agent/Conversation.swift
index 4cb2b452f..cac682780 100644
--- a/Sources/LiveKit/Agent/Conversation.swift
+++ b/Sources/LiveKit/Agent/Conversation.swift
@@ -58,7 +58,7 @@ open class Conversation: ObservableObject {
 
     public let room: Room
 
-    private let credentials: any CredentialsProvider
+    private let tokenSource: any TokenSource
     private let senders: [any MessageSender]
     private let receivers: [any MessageReceiver]
 
@@ -68,8 +68,8 @@ open class Conversation: ObservableObject {
 
     // MARK: - Init
 
-    public init(credentials: CredentialsProvider, room: Room = .init(), agentName: String? = nil, senders: [any MessageSender]? = nil, receivers: [any MessageReceiver]? = nil) {
-        self.credentials = credentials
+    public init(tokenSource: TokenSource, room: Room = .init(), agentName: String? = nil, senders: [any MessageSender]? = nil, receivers: [any MessageReceiver]? = nil) {
+        self.tokenSource = tokenSource
         self.room = room
 
         let textMessageSender = TextMessageSender(room: room)
@@ -155,11 +155,11 @@ open class Conversation: ObservableObject {
             if preConnectAudio {
                 try await room.withPreConnectAudio(timeout: waitForAgent) {
                     await MainActor.run { self.isListening = true }
-                    try await self.room.connect(credentialsProvider: self.credentials, connectOptions: options, roomOptions: roomOptions)
+                    try await self.room.connect(tokenSource: self.tokenSource, connectOptions: options, roomOptions: roomOptions)
                     await MainActor.run { self.isListening = false }
                 }
             } else {
-                try await room.connect(credentialsProvider: credentials, connectOptions: options, roomOptions: roomOptions)
+                try await room.connect(tokenSource: tokenSource, connectOptions: options, roomOptions: roomOptions)
             }
         } catch {
             self.error = .failedToConnect(error)