adjustments

Author: hiroshihorie

lib/src/agent/agent.dart

@@ -55,17 +55,51 @@ class Agent extends ChangeNotifier {
   RemoteVideoTrack? get avatarVideoTrack => _avatarVideoTrack;
   RemoteVideoTrack? _avatarVideoTrack;
 
-  /// Indicates whether the agent is connected.
-  bool get isConnected => switch (_state) {
-        _AgentLifecycle.connected => true,
-        _AgentLifecycle.connecting => false,
-        _AgentLifecycle.disconnected => false,
-        _AgentLifecycle.failed => false,
-      };
+  /// Indicates whether the agent is connected and ready for conversation.
+  bool get isConnected {
+    if (_state != _AgentLifecycle.connected) {
+      return false;
+    }
+    return switch (_agentState) {
+      AgentState.LISTENING || AgentState.THINKING || AgentState.SPEAKING => true,
+      _ => false,
+    };
+  }
 
   /// Whether the agent is buffering audio prior to connecting.
   bool get isBuffering => _state == _AgentLifecycle.connecting && _isBuffering;
 
+  /// Whether the agent can currently listen for user input.
+  bool get canListen {
+    if (_state == _AgentLifecycle.connecting) {
+      return _isBuffering;
+    }
+    if (_state == _AgentLifecycle.connected) {
+      return switch (_agentState) {
+        AgentState.LISTENING || AgentState.THINKING || AgentState.SPEAKING => true,
+        _ => false,
+      };
+    }
+    return false;
+  }
+
+  /// Whether the agent is pending initialization.
+  bool get isPending {
+    if (_state == _AgentLifecycle.connecting) {
+      return !_isBuffering;
+    }
+    if (_state == _AgentLifecycle.connected) {
+      return switch (_agentState) {
+        AgentState.IDLE || AgentState.INITIALIZING => true,
+        _ => false,
+      };
+    }
+    return false;
+  }
+
+  /// Whether the agent finished or failed its session.
+  bool get isFinished => _state == _AgentLifecycle.disconnected || _state == _AgentLifecycle.failed;
+
   _AgentLifecycle _state = _AgentLifecycle.disconnected;
   bool _isBuffering = false;
 
@@ -179,11 +213,15 @@ class Agent extends ChangeNotifier {
 /// Describes why an [Agent] failed to connect.
 enum AgentFailure {
   /// The agent did not connect within the allotted timeout.
-  timeout;
+  timeout,
+
+  /// The agent left the room unexpectedly.
+  left;
 
   /// A human-readable error message.
   String get message => switch (this) {
         AgentFailure.timeout => 'Agent did not connect',
+        AgentFailure.left => 'Agent left the room unexpectedly',
       };
 }
 

lib/src/agent/session.dart

@@ -25,6 +25,7 @@ import '../logger.dart';
 import '../managers/event.dart';
 import '../participant/remote.dart';
 import '../support/disposable.dart';
+import '../token_source/jwt.dart';
 import '../token_source/token_source.dart';
 import '../types/other.dart';
 import 'agent.dart';
@@ -177,36 +178,43 @@ class Session extends DisposableChangeNotifier {
 
     final Duration timeout = _options.agentConnectTimeout;
 
-    Future<void> connect() async {
+    Future<bool> connect() async {
       final response = await _tokenSourceConfiguration.fetch();
       await room.connect(
         response.serverUrl,
         response.participantToken,
       );
+      return response.dispatchesAgent();
     }
 
     try {
+      final bool dispatchesAgent;
       if (_options.preConnectAudio) {
-        await room.withPreConnectAudio(
+        dispatchesAgent = await room.withPreConnectAudio(
           () async {
             _setConnectionState(ConnectionState.connecting);
             _agent.connecting(buffering: true);
-            await connect();
+            return connect();
           },
           timeout: timeout,
         );
       } else {
         _setConnectionState(ConnectionState.connecting);
         _agent.connecting(buffering: false);
-        await connect();
+        dispatchesAgent = await connect();
         await room.localParticipant?.setMicrophoneEnabled(true);
       }
 
-      _agentTimeoutTimer = Timer(timeout, () {
-        if (isConnected && !_agent.isConnected) {
-          _agent.failed(AgentFailure.timeout);
-        }
-      });
+      if (dispatchesAgent) {
+        _agentTimeoutTimer = Timer(timeout, () {
+          if (isConnected && !_agent.isConnected) {
+            _agent.failed(AgentFailure.timeout);
+          }
+        });
+      } else {
+        _agentTimeoutTimer?.cancel();
+        _agentTimeoutTimer = null;
+      }
     } catch (error, stackTrace) {
       logger.warning('Session.start() failed: $error', error, stackTrace);
       _setError(SessionError.connection(error));
@@ -300,27 +308,26 @@ class Session extends DisposableChangeNotifier {
   }
 
   void _handleRoomEvent(RoomEvent event) {
+    bool shouldUpdateAgent = false;
+
     if (event is RoomConnectedEvent || event is RoomReconnectedEvent) {
       _setConnectionState(ConnectionState.connected);
+      shouldUpdateAgent = true;
     } else if (event is RoomReconnectingEvent) {
       _setConnectionState(ConnectionState.reconnecting);
+      shouldUpdateAgent = true;
     } else if (event is RoomDisconnectedEvent) {
       _setConnectionState(ConnectionState.disconnected);
       _agent.disconnected();
+      shouldUpdateAgent = true;
+    }
+
+    if (event is ParticipantEvent) {
+      shouldUpdateAgent = true;
     }
 
-    switch (event) {
-      case ParticipantConnectedEvent _:
-      case ParticipantDisconnectedEvent _:
-      case ParticipantAttributesChanged _:
-      case TrackPublishedEvent _:
-      case TrackUnpublishedEvent _:
-      case RoomConnectedEvent _:
-      case RoomReconnectedEvent _:
-      case RoomReconnectingEvent _:
-        _updateAgent();
-      default:
-        break;
+    if (shouldUpdateAgent) {
+      _updateAgent();
     }
   }
 
@@ -336,6 +343,8 @@ class Session extends DisposableChangeNotifier {
     final RemoteParticipant? firstAgent = room.agentParticipants.firstOrNull;
     if (firstAgent != null) {
       _agent.connected(firstAgent);
+    } else if (_agent.isConnected) {
+      _agent.failed(AgentFailure.left);
     } else {
       _agent.connecting(buffering: _options.preConnectAudio);
     }

lib/src/token_source/jwt.dart

@@ -15,6 +15,7 @@
 import 'package:dart_jsonwebtoken/dart_jsonwebtoken.dart';
 import 'package:json_annotation/json_annotation.dart';
 
+import 'room_configuration.dart';
 import 'token_source.dart';
 
 part 'jwt.g.dart';
@@ -75,6 +76,18 @@ class LiveKitJwtPayload {
     return null;
   }
 
+  /// Room configuration embedded in the token, if present.
+  RoomConfiguration? get roomConfiguration {
+    final raw = _claims['roomConfig'] ?? _claims['room_config'];
+    if (raw is Map<String, dynamic>) {
+      return RoomConfiguration.fromJson(Map<String, dynamic>.from(raw));
+    }
+    if (raw is Map) {
+      return RoomConfiguration.fromJson(Map<String, dynamic>.from(raw));
+    }
+    return null;
+  }
+
   /// Token expiration instant in UTC.
   DateTime? get expiresAt => _dateTimeFor('exp');
 
@@ -203,6 +216,12 @@ extension TokenSourceJwt on TokenSourceResponse {
 
     return true;
   }
+
+  /// Returns `true` when the token's room configuration dispatches at least one agent.
+  bool dispatchesAgent() {
+    final agents = jwtPayload?.roomConfiguration?.agents;
+    return agents != null && agents.isNotEmpty;
+  }
 }
 
 /// Extension to extract LiveKit-specific claims from JWT tokens.

test/token/token_source_test.dart

@@ -174,6 +174,14 @@ void main() {
           'hidden': false,
           'recorder': true,
         },
+        roomConfig: {
+          'agents': [
+            {
+              'agent_name': 'demo-agent',
+              'metadata': '{"foo":"bar"}',
+            }
+          ]
+        },
       );
 
       final response = TokenSourceResponse(
@@ -201,6 +209,42 @@ void main() {
       expect(grant.canPublishSources, ['camera', 'screen']);
       expect(grant.hidden, isFalse);
       expect(grant.recorder, isTrue);
+
+      final config = payload.roomConfiguration;
+      expect(config, isNotNull);
+      expect(config!.agents, isNotNull);
+      expect(config.agents, hasLength(1));
+      expect(config.agents!.first.agentName, 'demo-agent');
+      expect(config.agents!.first.metadata, '{"foo":"bar"}');
+    });
+  });
+
+  group('TokenSourceResponse', () {
+    test('dispatchesAgent returns true when JWT config includes agents', () {
+      final token = _generateToken(
+        roomConfig: {
+          'agents': [
+            {'agent_name': 'assistant'}
+          ]
+        },
+      );
+
+      final response = TokenSourceResponse(
+        serverUrl: 'https://test.livekit.io',
+        participantToken: token,
+      );
+
+      expect(response.dispatchesAgent(), isTrue);
+    });
+
+    test('dispatchesAgent returns false when JWT lacks agents', () {
+      final token = _generateToken();
+      final response = TokenSourceResponse(
+        serverUrl: 'https://test.livekit.io',
+        participantToken: token,
+      );
+
+      expect(response.dispatchesAgent(), isFalse);
     });
   });
 
@@ -445,6 +489,7 @@ String _generateToken({
   String? metadata,
   Map<String, String>? attributes,
   Map<String, dynamic>? video,
+  Map<String, dynamic>? roomConfig,
 }) {
   final payload = <String, dynamic>{
     'sub': subject ?? 'test-participant',
@@ -483,6 +528,10 @@ String _generateToken({
     payload['attributes'] = Map<String, String>.from(attributes);
   }
 
+  if (roomConfig != null) {
+    payload['roomConfig'] = roomConfig;
+  }
+
   final jwt = JWT(payload);
   return jwt.sign(SecretKey('test-secret'));
 }