poll method

Stream<AgentSnapshot<State>> poll({
  1. Duration interval = const Duration(seconds: 1),
  2. int maxConsecutiveMisses = 10,
  3. bool metadataOnly = false,
})

Yields status until a terminal state.

A snapshot can be briefly absent right after DetachedTask is created (the background worker hasn't persisted the first snapshot yet), so a null read is tolerated. But a snapshot that never appears (deleted, or a bad id) would otherwise loop forever and leak this poller, so give up after maxConsecutiveMisses consecutive misses.

Pass metadataOnly when the poll only branches on where the task stands (its status): the yielded snapshots carry the shaped metadata without the state payload, so a large conversation history is not loaded each tick.

Implementation

Stream<AgentSnapshot<State>> poll({
  Duration interval = const Duration(seconds: 1),
  int maxConsecutiveMisses = 10,
  bool metadataOnly = false,
}) async* {
  var misses = 0;
  while (true) {
    final snap = await _transport.getSnapshot(
      snapshotId: snapshotId,
      context: _context,
      metadataOnly: metadataOnly,
    );
    if (snap == null) {
      if (++misses >= maxConsecutiveMisses) {
        throw StateError('Snapshot $snapshotId not found.');
      }
    } else {
      misses = 0;
      yield AgentSnapshot<State>._(snap, _stateSchema);
      final status = snap.status;
      if (status != null && _terminalStatuses.contains(status.value)) return;
    }
    await Future<void>.delayed(interval);
  }
}