@livekit/agents 1.2.0 → 1.2.1

package/src/llm/utils.ts

@@ -7,6 +7,7 @@ import sharp from 'sharp';
 import type { UnknownUserData } from '../voice/run_context.js';
 import type { ChatContext } from './chat_context.js';
 import {
+  type ChatContent,
   type ChatItem,
   FunctionCall,
   FunctionCallOutput,
@@ -241,6 +242,133 @@ export async function executeToolCall(
   }
 }
 
+export interface FormatChatHistoryOptions {
+  includeIds?: boolean;
+  includeTimestamps?: boolean;
+}
+
+/**
+ * Render a chat context into a readable multiline string for debugging and logging.
+ */
+export function formatChatHistory(
+  chatCtx: ChatContext,
+  options: FormatChatHistoryOptions = {},
+): string {
+  const { includeIds = false, includeTimestamps = false } = options;
+
+  if (chatCtx.items.length === 0) {
+    return 'Chat history (0 items)';
+  }
+
+  const formattedItems = chatCtx.items.map((item, index) =>
+    formatChatHistoryItem(item, index, {
+      includeIds,
+      includeTimestamps,
+    }),
+  );
+
+  return [
+    `Chat history (${chatCtx.items.length} items)`,
+    ...formattedItems.flatMap((item) => ['', item]),
+  ].join('\n');
+}
+
+function formatChatHistoryItem(
+  item: ChatItem,
+  index: number,
+  options: Required<FormatChatHistoryOptions>,
+): string {
+  const headerParts = [`[${index}]`];
+
+  if (item.type === 'message') {
+    headerParts.push('message', item.role);
+  } else if (item.type === 'function_call') {
+    headerParts.push('function_call', item.name, `call_id=${item.callId}`);
+  } else if (item.type === 'function_call_output') {
+    headerParts.push('function_call_output', item.name || '(unnamed)', `call_id=${item.callId}`);
+    if (item.isError) {
+      headerParts.push('error=true');
+    }
+  } else {
+    headerParts.push('agent_handoff');
+  }
+
+  if (options.includeIds) {
+    headerParts.push(`id=${item.id}`);
+  }
+
+  if (options.includeTimestamps) {
+    headerParts.push(`created_at=${item.createdAt.toFixed(3)}`);
+  }
+
+  const body = formatChatHistoryItemBody(item);
+  if (!body) {
+    return headerParts.join(' ');
+  }
+
+  return `${headerParts.join(' ')}\n${indentBlock(body, '  ')}`;
+}
+
+function formatChatHistoryItemBody(item: ChatItem): string {
+  if (item.type === 'message') {
+    const content = item.content.map((part) => formatMessageContentPart(part)).join('\n');
+    return content.trim() ? content : '(empty)';
+  }
+
+  if (item.type === 'function_call') {
+    return prettyJsonText(item.args);
+  }
+
+  if (item.type === 'function_call_output') {
+    return prettyJsonText(item.output);
+  }
+
+  return `${item.oldAgentId ?? '(none)'} -> ${item.newAgentId}`;
+}
+
+function formatMessageContentPart(part: ChatContent): string {
+  if (typeof part === 'string') {
+    return part;
+  }
+
+  if (part.type === 'image_content') {
+    if (typeof part.image === 'string') {
+      return `[image url=${truncateText(part.image, 120)}]`;
+    }
+
+    return `[image frame=${part.image.width}x${part.image.height}]`;
+  }
+
+  if (part.transcript) {
+    return `[audio transcript=${JSON.stringify(truncateText(part.transcript, 120))}]`;
+  }
+
+  return `[audio frames=${part.frame.length}]`;
+}
+
+function prettyJsonText(text: string): string {
+  try {
+    return JSON.stringify(JSON.parse(text), null, 2);
+  } catch {
+    return text;
+  }
+}
+
+function truncateText(text: string, maxLength: number): string {
+  if (text.length <= maxLength) {
+    return text;
+  }
+
+  return `${text.slice(0, Math.max(0, maxLength - 3))}...`;
+}
+
+function indentBlock(text: string, indent: string): string {
+  return text
+    .split('\n')
+    .map((line) => `${indent}${line}`)
+    .join('\n');
+}
+
 /**
  * Standard dynamic-programming LCS to get the common subsequence
  * of IDs (in order) that appear in both old_ids and new_ids.

package/src/stt/stt.ts

@@ -248,7 +248,15 @@ export abstract class SpeechStream implements AsyncIterableIterator<SpeechEvent>
     startSoon(() => this.mainTask().finally(() => this.queue.close()));
   }
 
-  private async mainTask() {
+  /**
+   * Runs the STT with retry logic. Errors are emitted via {@link STT} error events
+   * and then re-thrown to trigger `.finally()` cleanup.
+   *
+   * @throws {APIError} When the STT request fails with a non-retryable error
+   * @throws {APIConnectionError} When all retry attempts are exhausted
+   * @internal Not annotated with Throws<> because this is fire-and-forget via startSoon()
+   */
+  private async mainTask(): Promise<void> {
     for (let i = 0; i < this._connOptions.maxRetry + 1; i++) {
       try {
         return await this.run();

package/src/tts/fallback_adapter.ts

@@ -2,6 +2,7 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import { AudioResampler } from '@livekit/rtc-node';
+import type { Throws } from '@livekit/throws-transformer/throws';
 import { APIConnectionError, APIError } from '../_exceptions.js';
 import { log } from '../log.js';
 import { basic } from '../tokenize/index.js';
@@ -306,7 +307,10 @@ class FallbackChunkedStream extends ChunkedStream {
     this.connOptions = connOptions;
   }
 
-  protected async run(): Promise<void> {
+  /**
+   * @throws {APIConnectionError} When all TTS providers have been exhausted
+   */
+  protected async run(): Promise<Throws<void, APIConnectionError>> {
     const allTTSFailed = this.adapter.status.every((s) => !s.available);
     let lastRequestId: string = '';
     let lastSegmentId: string = '';
@@ -406,7 +410,10 @@ class FallbackSynthesizeStream extends SynthesizeStream {
     this.adapter = adapter;
   }
 
-  protected async run(): Promise<void> {
+  /**
+   * @throws {APIConnectionError} When all TTS providers have been exhausted
+   */
+  protected async run(): Promise<Throws<void, APIConnectionError>> {
     const allTTSFailed = this.adapter.status.every((s) => !s.available);
     if (allTTSFailed) {
       this._logger.warn('All fallback TTS instances failed, retrying from first...');

package/src/typed_promise.ts

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+type InferErrors<T> = T extends TypedPromise<any, infer E> ? E : never;
+
+interface PromiseRejectedResult<E> {
+  status: 'rejected';
+  reason: E;
+}
+
+type SettledResult<T> =
+  T extends TypedPromise<infer U, infer E>
+    ? PromiseFulfilledResult<U> | PromiseRejectedResult<E>
+    : T extends PromiseLike<infer U>
+      ? PromiseFulfilledResult<U> | PromiseRejectedResult<unknown>
+      : PromiseFulfilledResult<T> | PromiseRejectedResult<unknown>;
+
+export default class TypedPromise<T, E extends Error> extends Promise<T> {
+  // eslint-disable-next-line @typescript-eslint/no-useless-constructor
+  constructor(
+    executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason: E) => void) => void,
+  ) {
+    super(executor);
+  }
+
+  catch<TResult = never>(
+    onrejected?: ((reason: E) => TResult | PromiseLike<TResult>) | null | undefined,
+  ): TypedPromise<T | TResult, E> {
+    return super.catch(onrejected);
+  }
+
+  static resolve: {
+    (): TypedPromise<void, never>;
+    <V>(value: V): TypedPromise<Awaited<V>, never>;
+  } = <V>(value?: V): TypedPromise<Awaited<V>, never> => {
+    return super.resolve(value) as TypedPromise<Awaited<V>, never>;
+  };
+
+  static reject<E extends Error>(reason: E): TypedPromise<never, E> {
+    return super.reject(reason);
+  }
+
+  static all<T extends readonly unknown[] | []>(
+    values: T,
+  ): TypedPromise<{ -readonly [P in keyof T]: Awaited<T[P]> }, InferErrors<T[number]>> {
+    return super.all(values) as any;
+  }
+
+  static allSettled<T extends readonly unknown[] | []>(
+    values: T,
+  ): TypedPromise<{ -readonly [P in keyof T]: SettledResult<T[P]> }, never> {
+    return super.allSettled(values) as any;
+  }
+
+  static race<T extends readonly (TypedPromise<any, any> | any)[]>(
+    values: T,
+  ): TypedPromise<
+    T[number] extends TypedPromise<infer U, any>
+      ? U
+      : T[number] extends PromiseLike<infer U>
+        ? U
+        : Awaited<T[number]>,
+    InferErrors<T[number]>
+  > {
+    return super.race(values);
+  }
+}

package/src/utils.ts

@@ -789,11 +789,11 @@ export type DelayOptions = {
  */
 export function delay(ms: number, options: DelayOptions = {}): Promise<void> {
   const { signal } = options;
-  if (signal?.aborted) return Promise.reject(signal.reason);
+  if (signal?.aborted) return Promise.reject(signal.reason ?? new Error('delay aborted'));
   return new Promise((resolve, reject) => {
     const abort = () => {
       clearTimeout(i);
-      reject(signal?.reason);
+      reject(signal?.reason ?? new Error('delay aborted'));
     };
     const done = () => {
       signal?.removeEventListener('abort', abort);