@livekit/agents 0.0.0-20260120144724

package/src/stream/deferred_stream.ts

@@ -0,0 +1,127 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import type {
+  ReadableStream,
+  ReadableStreamDefaultReader,
+  WritableStreamDefaultWriter,
+} from 'node:stream/web';
+import { IdentityTransform } from './identity_transform.js';
+
+/**
+ * Check if error is related to stream cleanup operations.
+ *
+ * These errors are expected when calling reader.read() after releaseLock()
+ * or when writing to already closed streams during cleanup:
+ *
+ * Invalid state: Releasing reader
+ * Invalid state: The reader is not attached to a stream
+ * Invalid state: Controller is already closed
+ * Invalid state: WritableStream is closed
+ */
+export function isStreamReaderReleaseError(e: unknown) {
+  const allowedMessages = [
+    'Invalid state: Releasing reader',
+    'Invalid state: The reader is not attached to a stream',
+    'Controller is already closed',
+    'WritableStream is closed',
+  ];
+
+  if (e instanceof TypeError) {
+    return allowedMessages.some((message) => e.message.includes(message));
+  }
+
+  return false;
+}
+export class DeferredReadableStream<T> {
+  private transform: IdentityTransform<T>;
+  private writer: WritableStreamDefaultWriter<T>;
+  private sourceReader?: ReadableStreamDefaultReader<T>;
+
+  constructor() {
+    this.transform = new IdentityTransform<T>();
+    this.writer = this.transform.writable.getWriter();
+  }
+
+  get stream() {
+    return this.transform.readable;
+  }
+
+  get isSourceSet() {
+    return !!this.sourceReader;
+  }
+
+  /**
+   * Call once the actual source is ready.
+   */
+  setSource(source: ReadableStream<T>) {
+    if (this.isSourceSet) {
+      throw new Error('Stream source already set');
+    }
+
+    this.sourceReader = source.getReader();
+    this.pump();
+  }
+
+  private async pump() {
+    let sourceError: unknown;
+
+    try {
+      while (true) {
+        const { done, value } = await this.sourceReader!.read();
+        if (done) break;
+        await this.writer.write(value);
+      }
+    } catch (e) {
+      // skip stream cleanup related errors
+      if (isStreamReaderReleaseError(e)) return;
+
+      sourceError = e;
+    } finally {
+      // any other error from source will be propagated to the consumer
+      if (sourceError) {
+        try {
+          this.writer.abort(sourceError);
+        } catch (e) {
+          // ignore if writer is already closed
+        }
+        return;
+      }
+
+      // release lock so this.stream.getReader().read() will terminate with done: true
+      try {
+        this.writer.releaseLock();
+      } catch (e) {
+        // ignore if writer lock is already released
+      }
+
+      // we only close the writable stream after done
+      try {
+        await this.transform.writable.close();
+        // NOTE: we do not cancel this.transform.readable as there might be access to
+        // this.transform.readable.getReader() outside that blocks this cancellation
+        // hence, user is responsible for canceling reader on their own
+      } catch (e) {
+        // ignore TypeError: Invalid state: WritableStream is closed
+        // in case stream reader is already closed, this will throw
+        // but we ignore it as we are closing the stream anyway
+      }
+    }
+  }
+
+  /**
+   * Detach the source stream and clean up resources.
+   */
+  async detachSource() {
+    if (!this.isSourceSet) {
+      // No-op if source was never set - this is a common case during cleanup
+      return;
+    }
+
+    // release lock will make any pending read() throw TypeError
+    // which are expected, and we intentionally catch those error
+    // using isStreamReaderReleaseError
+    // this will unblock any pending read() inside the async for loop
+    this.sourceReader!.releaseLock();
+  }
+}

package/src/stream/identity_transform.test.ts

@@ -0,0 +1,179 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, it } from 'vitest';
+import { IdentityTransform } from './identity_transform.js';
+
+describe('IdentityTransform', () => {
+  it('should handle stream with one value', async () => {
+    const transform = new IdentityTransform<string>();
+    const writer = transform.writable.getWriter();
+    const reader = transform.readable.getReader();
+
+    const inputValue = 'single value';
+
+    await writer.write(inputValue);
+    await writer.close();
+
+    const result = await reader.read();
+    expect(result.done).toBe(false);
+    expect(result.value).toBe(inputValue);
+
+    const nextResult = await reader.read();
+    expect(nextResult.done).toBe(true);
+  });
+
+  it('should handle multiple values in sequence', async () => {
+    const transform = new IdentityTransform<string>();
+    const writer = transform.writable.getWriter();
+    const reader = transform.readable.getReader();
+
+    const inputValues = ['first', 'second', 'third'];
+
+    // Write all values
+    for (const value of inputValues) {
+      await writer.write(value);
+    }
+    await writer.close();
+
+    // Read all values
+    const results: string[] = [];
+    let result = await reader.read();
+    while (!result.done) {
+      results.push(result.value);
+      result = await reader.read();
+    }
+
+    expect(results).toEqual(inputValues);
+  });
+
+  it('should handle null and undefined values', async () => {
+    const transform = new IdentityTransform<string | null | undefined>();
+    const writer = transform.writable.getWriter();
+    const reader = transform.readable.getReader();
+
+    const inputValues = ['test', null, undefined, 'another'];
+
+    // Write all values
+    for (const value of inputValues) {
+      await writer.write(value);
+    }
+    await writer.close();
+
+    // Read all values
+    const results: (string | null | undefined)[] = [];
+    let result = await reader.read();
+    while (!result.done) {
+      results.push(result.value);
+      result = await reader.read();
+    }
+
+    expect(results).toEqual(inputValues);
+  });
+
+  it('should handle arrays', async () => {
+    const transform = new IdentityTransform<number[]>();
+    const writer = transform.writable.getWriter();
+    const reader = transform.readable.getReader();
+
+    const inputValue = [1, 2, 3, 4, 5];
+
+    await writer.write(inputValue);
+    await writer.close();
+
+    const result = await reader.read();
+
+    expect(result.done).toBe(false);
+    expect(result.value).toEqual(inputValue);
+    expect(result.value).toBe(inputValue); // Should be the same reference
+
+    const nextResult = await reader.read();
+    expect(nextResult.done).toBe(true);
+  });
+
+  it('should work with streamed data', async () => {
+    const transform = new IdentityTransform<string>();
+    const writer = transform.writable.getWriter();
+    const reader = transform.readable.getReader();
+
+    const testData = ['chunk1', 'chunk2', 'chunk3'];
+
+    // Write data asynchronously to simulate streaming
+    const writePromise = (async () => {
+      for (const chunk of testData) {
+        await writer.write(chunk);
+      }
+      await writer.close();
+    })();
+
+    // Read data as it comes through
+    const results: string[] = [];
+    let result = await reader.read();
+    while (!result.done) {
+      results.push(result.value);
+      result = await reader.read();
+    }
+
+    await writePromise;
+    expect(results).toEqual(testData);
+  });
+
+  it('should handle empty stream', async () => {
+    const transform = new IdentityTransform<string>();
+    const writer = transform.writable.getWriter();
+    const reader = transform.readable.getReader();
+
+    // Close immediately without writing anything
+    await writer.close();
+
+    // Should immediately be done
+    const result = await reader.read();
+    expect(result.done).toBe(true);
+  });
+
+  it('should handle writer closing while reading is in progress', async () => {
+    const transform = new IdentityTransform<string>();
+    const writer = transform.writable.getWriter();
+    const reader = transform.readable.getReader();
+
+    const testData = ['chunk1', 'chunk2', 'chunk3'];
+    const results: string[] = [];
+
+    // Start writing some data
+    await writer.write(testData[0]);
+    await writer.write(testData[1]);
+
+    // Start reading concurrently
+    const readPromise = (async () => {
+      let result = await reader.read();
+      while (!result.done) {
+        results.push(result.value);
+        result = await reader.read();
+      }
+    })();
+
+    // Write one more chunk and then close the writer while reading
+    await writer.write(testData[2]);
+    await writer.close();
+
+    // Wait for reading to complete
+    await readPromise;
+
+    // Should have received all the data
+    expect(results).toEqual(testData);
+  });
+
+  it('should handle a pending read when the writer is closed', async () => {
+    const transform = new IdentityTransform<string>();
+    const writer = transform.writable.getWriter();
+    const reader = transform.readable.getReader();
+
+    const readPromise = reader.read();
+
+    await writer.close();
+
+    const result = await readPromise;
+    expect(result.done).toBe(true);
+    expect(result.value).toBeUndefined();
+  });
+});

package/src/stream/identity_transform.ts

@@ -0,0 +1,18 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { TransformStream } from 'node:stream/web';
+
+export class IdentityTransform<T> extends TransformStream<T, T> {
+  constructor() {
+    super(
+      {
+        transform: (chunk, controller) => controller.enqueue(chunk),
+      },
+      // By default the transfor stream will buffer only one chunk at a time.
+      // In order to follow the python agents channel.py, we set set the capaciy to be effectively infinite.
+      { highWaterMark: Number.MAX_SAFE_INTEGER },
+      { highWaterMark: Number.MAX_SAFE_INTEGER },
+    );
+  }
+}

package/src/stream/index.ts

@@ -0,0 +1,7 @@
+// SPDX-FileCopyrightText: 2024 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+export { DeferredReadableStream } from './deferred_stream.js';
+export { IdentityTransform } from './identity_transform.js';
+export { mergeReadableStreams } from './merge_readable_streams.js';
+export { createStreamChannel, type StreamChannel } from './stream_channel.js';

package/src/stream/merge_readable_streams.ts

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { ReadableStream } from 'node:stream/web';
+import { withResolvers } from '../utils.js';
+
+// Adapted from https://github.com/denoland/std/blob/main/streams/merge_readable_streams.ts
+// we manually adapted to make ReadableStream<T> typing compatible with our current node
+// version as well as typescript configuration
+export function mergeReadableStreams<T>(...streams: ReadableStream<T>[]): ReadableStream<T> {
+  const resolvePromises = streams.map(() => withResolvers<void>());
+  return new ReadableStream<T>({
+    start(controller) {
+      let mustClose = false;
+      Promise.all(resolvePromises.map(({ promise }) => promise))
+        .then(() => {
+          controller.close();
+        })
+        .catch((error) => {
+          mustClose = true;
+          controller.error(error);
+        });
+      for (const [index, stream] of streams.entries()) {
+        (async () => {
+          try {
+            for await (const data of stream) {
+              if (mustClose) {
+                break;
+              }
+              controller.enqueue(data);
+            }
+            resolvePromises[index]!.resolve();
+          } catch (error) {
+            resolvePromises[index]!.reject(error);
+          }
+        })();
+      }
+    },
+  });
+}

package/src/stream/stream_channel.test.ts

@@ -0,0 +1,166 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, it } from 'vitest';
+import { createStreamChannel } from './stream_channel.js';
+
+describe('StreamChannel', () => {
+  it('should write and read a single value', async () => {
+    const channel = createStreamChannel<string>();
+    const reader = channel.stream().getReader();
+
+    await channel.write('test value');
+    await channel.close();
+
+    const result = await reader.read();
+    expect(result.done).toBe(false);
+    expect(result.value).toBe('test value');
+
+    const nextResult = await reader.read();
+    expect(nextResult.done).toBe(true);
+  });
+
+  it('should write and read multiple values in sequence', async () => {
+    const channel = createStreamChannel<string>();
+    const reader = channel.stream().getReader();
+
+    const testValues = ['first', 'second', 'third'];
+
+    for (const value of testValues) {
+      await channel.write(value);
+    }
+    await channel.close();
+
+    const results: string[] = [];
+    let result = await reader.read();
+    while (!result.done) {
+      results.push(result.value);
+      result = await reader.read();
+    }
+
+    expect(results).toEqual(testValues);
+  });
+
+  it('should handle arrays', async () => {
+    const channel = createStreamChannel<number[]>();
+    const reader = channel.stream().getReader();
+
+    const testArray = [1, 2, 3, 4, 5];
+    await channel.write(testArray);
+    await channel.close();
+
+    const result = await reader.read();
+    expect(result.value).toEqual(testArray);
+    expect(result.value).toBe(testArray);
+  });
+
+  it('should work with concurrent writing and reading', async () => {
+    const channel = createStreamChannel<string>();
+    const reader = channel.stream().getReader();
+
+    const testData = ['chunk1', 'chunk2', 'chunk3'];
+    const results: string[] = [];
+
+    const readPromise = (async () => {
+      let result = await reader.read();
+      while (!result.done) {
+        results.push(result.value);
+        result = await reader.read();
+      }
+    })();
+
+    for (const chunk of testData) {
+      await channel.write(chunk);
+    }
+    await channel.close();
+
+    await readPromise;
+    expect(results).toEqual(testData);
+  });
+
+  it('should handle empty stream', async () => {
+    const channel = createStreamChannel<string>();
+    const reader = channel.stream().getReader();
+
+    await channel.close();
+
+    const result = await reader.read();
+    expect(result.done).toBe(true);
+  });
+
+  it('should handle non-awaited sequential writes', async () => {
+    const channel = createStreamChannel<number>();
+    const reader = channel.stream().getReader();
+
+    const testNumbers = Array.from({ length: 100 }, (_, i) => i);
+
+    for (const num of testNumbers) {
+      channel.write(num);
+    }
+    channel.close();
+
+    const results: number[] = [];
+    let result = await reader.read();
+    while (!result.done) {
+      results.push(result.value);
+      result = await reader.read();
+    }
+
+    expect(results).toEqual(testNumbers);
+  });
+
+  it('should handle double closing without error', async () => {
+    const channel = createStreamChannel<string>();
+    const reader = channel.stream().getReader();
+
+    await channel.write('test');
+
+    await channel.close();
+    // Close again - should not throw
+    await expect(channel.close()).resolves.toBeUndefined();
+
+    const result = await reader.read();
+    expect(result.done).toBe(false);
+    expect(result.value).toBe('test');
+
+    const nextResult = await reader.read();
+    expect(nextResult.done).toBe(true);
+  });
+
+  it('should gracefully handle close while read is pending', async () => {
+    const channel = createStreamChannel<string>();
+    const reader = channel.stream().getReader();
+
+    const readPromise = reader.read();
+
+    await channel.close();
+
+    const result = await readPromise;
+    expect(result.done).toBe(true);
+    expect(result.value).toBeUndefined();
+  });
+
+  it('should complete all pending reads when closed', async () => {
+    const channel = createStreamChannel<number>();
+    const reader = channel.stream().getReader();
+
+    const read1 = reader.read();
+    const read2 = reader.read();
+    const read3 = reader.read();
+
+    await channel.write(42);
+    await channel.write(43);
+    await channel.close();
+
+    const result1 = await read1;
+    expect(result1.done).toBe(false);
+    expect(result1.value).toBe(42);
+
+    const result2 = await read2;
+    expect(result2.done).toBe(false);
+    expect(result2.value).toBe(43);
+
+    const result3 = await read3;
+    expect(result3.done).toBe(true);
+  });
+});

package/src/stream/stream_channel.ts

@@ -0,0 +1,44 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import type { ReadableStream } from 'node:stream/web';
+import { IdentityTransform } from './identity_transform.js';
+
+export interface StreamChannel<T, E extends Error = Error> {
+  write(chunk: T): Promise<void>;
+  close(): Promise<void>;
+  stream(): ReadableStream<T>;
+  abort(error: E): Promise<void>;
+  readonly closed: boolean;
+}
+
+export function createStreamChannel<T, E extends Error = Error>(): StreamChannel<T, E> {
+  const transform = new IdentityTransform<T>();
+  const writer = transform.writable.getWriter();
+  let isClosed = false;
+
+  return {
+    write: (chunk: T) => writer.write(chunk),
+    stream: () => transform.readable,
+    abort: (error: E) => {
+      return writer.abort(error);
+    },
+    close: async () => {
+      try {
+        const result = await writer.close();
+        isClosed = true;
+        return result;
+      } catch (e) {
+        if (e instanceof Error && e.name === 'TypeError') {
+          // Ignore error if the stream is already closed
+          isClosed = true;
+          return;
+        }
+        throw e;
+      }
+    },
+    get closed() {
+      return isClosed;
+    },
+  };
+}

package/src/stt/index.ts

@@ -0,0 +1,15 @@
+// SPDX-FileCopyrightText: 2024 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+export {
+  type SpeechEvent,
+  type SpeechData,
+  type STTCapabilities,
+  type RecognitionUsage,
+  type STTCallbacks,
+  SpeechEventType,
+  STT,
+  SpeechStream,
+} from './stt.js';
+export { StreamAdapter, StreamAdapterWrapper } from './stream_adapter.js';