feat(stream): document and publicly export readStream and toStream

Surface the readStream/toStream helpers under the `stream` namespace
alongside the other stream utilities, and add full TSDoc describing their
abort/cancel semantics so they are discoverable and supported for user code.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: toubatbrian

.changeset/export-stream-helpers.md

@@ -0,0 +1,5 @@
+---
+'@livekit/agents': patch
+---
+
+Document and publicly export the `readStream` and `toStream` stream helpers. `readStream` consumes a `ReadableStream` as an abortable async generator, and `toStream` adapts an `AsyncIterable` into a `ReadableStream`. Both are now surfaced under the `stream` namespace alongside the other stream utilities and carry full TSDoc describing their abort/cancel semantics.

agents/src/stream/index.ts

@@ -6,3 +6,4 @@ export { IdentityTransform } from './identity_transform.js';
 export { mergeReadableStreams } from './merge_readable_streams.js';
 export { MultiInputStream } from './multi_input_stream.js';
 export { createStreamChannel, type StreamChannel } from './stream_channel.js';
+export { readStream, toStream } from '../utils.js';

agents/src/utils.ts

@@ -1311,8 +1311,35 @@ export async function waitForTrackPublication({
 }
 
 /**
- * Yields values from a ReadableStream until the stream ends or the signal is aborted.
- * Handles reader cleanup and stream-release errors internally.
+ * Consume a {@link ReadableStream} as an async generator, yielding each chunk in
+ * order until the stream ends or the optional {@link AbortSignal} is aborted.
+ *
+ * This is a convenience wrapper around the Web Streams reader API that handles the
+ * boilerplate of acquiring a reader, looping over `reader.read()`, and releasing the
+ * reader lock when iteration finishes.
+ *
+ * Key behaviors:
+ * - Acquires a reader for the lifetime of the iteration and always releases the lock
+ *   when the generator completes, throws, or is returned early (e.g. `break`).
+ * - If a `signal` is provided, each read races against the abort signal; once aborted
+ *   the generator stops yielding and returns cleanly without throwing. If the signal is
+ *   already aborted before the first read, no values are yielded.
+ * - Errors raised by the underlying stream propagate to the caller; errors thrown while
+ *   releasing the reader lock during cleanup are swallowed (the source may already be
+ *   closed).
+ *
+ * @typeParam T - The type of the chunks emitted by the stream.
+ * @param stream - The readable stream to consume. The stream must not already be locked
+ *   to another reader.
+ * @param signal - Optional abort signal used to stop iteration early.
+ * @returns An async generator that yields each chunk read from the stream.
+ *
+ * @example
+ * ```ts
+ * for await (const chunk of readStream(response.body, controller.signal)) {
+ *   process(chunk);
+ * }
+ * ```
  */
 export async function* readStream<T>(
   stream: ReadableStream<T>,
@@ -1352,6 +1379,36 @@ export async function* readStream<T>(
   }
 }
 
+/**
+ * Adapt an {@link AsyncIterable} into a {@link ReadableStream}, enqueuing each value the
+ * iterable produces and closing the stream when the iterable is exhausted.
+ *
+ * This is the inverse of {@link readStream}: it lets an async generator or any other
+ * async-iterable source be consumed anywhere a Web {@link ReadableStream} is expected
+ * (piping, teeing, `Response` bodies, etc.).
+ *
+ * Key behaviors:
+ * - Pulls from the iterable eagerly in the stream's `start` callback and enqueues every
+ *   value until the iterable completes, at which point the stream is closed.
+ * - If the iterable throws, the error is forwarded to the stream's consumer via
+ *   `controller.error()`.
+ * - When the consumer cancels the stream, the underlying iterator's `return()` is invoked
+ *   (with the cancel reason) so the source can release resources, and no further values
+ *   are enqueued.
+ *
+ * @typeParam T - The type of the values produced by the iterable and emitted by the stream.
+ * @param iterable - The async iterable to adapt.
+ * @returns A readable stream that emits the values produced by `iterable`.
+ *
+ * @example
+ * ```ts
+ * async function* numbers() {
+ *   yield 1;
+ *   yield 2;
+ * }
+ * const stream = toStream(numbers());
+ * ```
+ */
 export function toStream<T>(iterable: AsyncIterable<T>): ReadableStream<T> {
   let iterator: AsyncIterator<T> | undefined;
   let cancelled = false;