align turn configurations

Author: toubatbrian

agents/src/voice/agent.ts

@@ -31,8 +31,8 @@ import type { VAD } from '../vad.js';
 import type { AgentActivity } from './agent_activity.js';
 import type { AgentSession, TurnDetectionMode } from './agent_session.js';
 import type { TimedString } from './io.js';
-import type { InterruptionConfig } from './turn_config/interruption.js';
-import type { TurnHandlingConfig } from './turn_config/turn_handling.js';
+import type { InterruptionOptions } from './turn_config/interruption.js';
+import type { TurnHandlingOptions } from './turn_config/turn_handling.js';
 import { migrateLegacyOptions } from './turn_config/utils.js';
 
 export const asyncLocalStorage = new AsyncLocalStorage<{ functionCall?: FunctionCall }>();
@@ -76,7 +76,7 @@ export interface AgentOptions<UserData> {
   tts?: TTS | TTSModelString;
   allowInterruptions?: boolean;
   minConsecutiveSpeechDelay?: number;
-  turnHandling?: TurnHandlingConfig;
+  turnHandling?: TurnHandlingOptions;
   useTtsAlignedTranscript?: boolean;
 }
 
@@ -86,8 +86,8 @@ export class Agent<UserData = any> {
   private _vad?: VAD;
   private _llm?: LLM | RealtimeModel;
   private _tts?: TTS;
-  private turnHandling?: TurnHandlingConfig;
-  private _interruptionDetection: InterruptionConfig['mode'];
+  private turnHandling?: TurnHandlingOptions;
+  private _interruptionDetection: InterruptionOptions['mode'];
   private _allowInterruptions?: boolean;
   private _useTtsAlignedTranscript?: boolean;
 
@@ -215,7 +215,7 @@ export class Agent<UserData = any> {
     return this.getActivityOrThrow().agentSession as AgentSession<UserData>;
   }
 
-  get interruptionDetection(): InterruptionConfig['mode'] {
+  get interruptionDetection(): InterruptionOptions['mode'] {
     return this._interruptionDetection;
   }
 

agents/src/voice/agent_session.ts

@@ -71,10 +71,10 @@ import {
 import type { UnknownUserData } from './run_context.js';
 import type { SpeechHandle } from './speech_handle.js';
 import { RunResult } from './testing/run_result.js';
-import type { InterruptionConfig } from './turn_config/interruption.js';
+import type { InterruptionOptions } from './turn_config/interruption.js';
 import type {
-  InternalTurnHandlingConfig,
-  TurnHandlingConfig,
+  InternalTurnHandlingOptions,
+  TurnHandlingOptions,
 } from './turn_config/turn_handling.js';
 import { migrateLegacyOptions } from './turn_config/utils.js';
 
@@ -103,7 +103,7 @@ export interface SessionOptions {
   /**
    * Configuration for turn handling.
    */
-  turnHandling: Partial<TurnHandlingConfig>;
+  turnHandling: Partial<TurnHandlingOptions>;
 
   useTtsAlignedTranscript: boolean;
 
@@ -122,7 +122,7 @@ export interface SessionOptions {
 }
 
 export interface InternalSessionOptions extends SessionOptions {
-  turnHandling: InternalTurnHandlingConfig;
+  turnHandling: InternalTurnHandlingOptions;
 }
 
 export const defaultSessionOptions = {
@@ -207,7 +207,7 @@ export class AgentSession<
   private sessionSpan?: Span;
   private agentSpeakingSpan?: Span;
 
-  private _interruptionDetection?: InterruptionConfig['mode'];
+  private _interruptionDetection?: InterruptionOptions['mode'];
 
   private _usageCollector: ModelUsageCollector = new ModelUsageCollector();
 

agents/src/voice/audio_recognition.ts

@@ -59,9 +59,13 @@ export interface RecognitionHooks {
 }
 
 export interface _TurnDetector {
+  /** The model name used by this turn detector. */
+  readonly model: string;
+  /** The provider name for this turn detector. */
+  readonly provider: string;
   unlikelyThreshold: (language?: string) => Promise<number | undefined>;
   supportsLanguage: (language?: string) => Promise<boolean>;
-  predictEndOfTurn(chatCtx: ChatContext): Promise<number>;
+  predictEndOfTurn(chatCtx: ChatContext, timeout?: number): Promise<number>;
 }
 
 export interface AudioRecognitionOptions {

agents/src/voice/turn_config/endpointing.ts

@@ -4,7 +4,13 @@
 /**
  * Configuration for endpointing, which determines when the user's turn is complete.
  */
-export interface EndpointingConfig {
+export interface EndpointingOptions {
+  /**
+   * Endpointing mode. `"fixed"` uses a fixed delay, `"dynamic"` adjusts delay based on
+   * end-of-utterance prediction.
+   * @defaultValue "fixed"
+   */
+  mode: 'fixed' | 'dynamic';
   /**
    * Minimum time in milliseconds since the last detected speech before the agent declares the user's
    * turn complete. In VAD mode this effectively behaves like `max(VAD silence, minDelay)`;
@@ -20,7 +26,8 @@ export interface EndpointingConfig {
   maxDelay: number;
 }
 
-export const defaultEndpointingConfig = {
+export const defaultEndpointingOptions = {
+  mode: 'fixed',
   minDelay: 500,
   maxDelay: 3000,
-} as const satisfies EndpointingConfig;
+} as const satisfies EndpointingOptions;

agents/src/voice/turn_config/interruption.ts

@@ -4,9 +4,15 @@
 /**
  * Configuration for interruption handling.
  */
-export interface InterruptionConfig {
+export interface InterruptionOptions {
   /**
-   * Interruption handling strategy.
+   * Whether interruptions are enabled.
+   * @defaultValue true
+   */
+  enabled: boolean;
+  /**
+   * Interruption handling strategy. `"adaptive"` for ML-based detection, `"vad"` for simple
+   * voice-activity detection. `undefined` means auto-detect.
    * @defaultValue undefined
    */
   mode: 'adaptive' | 'vad' | false | undefined;
@@ -39,11 +45,12 @@ export interface InterruptionConfig {
   resumeFalseInterruption: boolean;
 }
 
-export const defaultInterruptionConfig = {
+export const defaultInterruptionOptions = {
+  enabled: true,
   mode: undefined,
   discardAudioIfUninterruptible: true,
   minDuration: 500,
   minWords: 0,
   falseInterruptionTimeout: 2000,
   resumeFalseInterruption: true,
-} as const satisfies InterruptionConfig;
+} as const satisfies InterruptionOptions;

agents/src/voice/turn_config/turn_handling.ts

@@ -2,14 +2,14 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import type { TurnDetectionMode } from '../agent_session.js';
-import { type EndpointingConfig, defaultEndpointingConfig } from './endpointing.js';
-import { type InterruptionConfig, defaultInterruptionConfig } from './interruption.js';
+import { type EndpointingOptions, defaultEndpointingOptions } from './endpointing.js';
+import { type InterruptionOptions, defaultInterruptionOptions } from './interruption.js';
 
 /**
  * Configuration for the turn handling system. Used to configure the turn taking behavior of the
  * session.
  */
-export interface TurnHandlingConfig {
+export interface TurnHandlingOptions {
   /**
    * Strategy for deciding when the user has finished speaking.
    *
@@ -26,20 +26,20 @@ export interface TurnHandlingConfig {
   /**
    * Configuration for endpointing.
    */
-  endpointing: Partial<EndpointingConfig>;
+  endpointing: Partial<EndpointingOptions>;
   /**
    * Configuration for interruption handling.
    */
-  interruption: Partial<InterruptionConfig>;
+  interruption: Partial<InterruptionOptions>;
 }
 
-export interface InternalTurnHandlingConfig extends TurnHandlingConfig {
-  endpointing: EndpointingConfig;
-  interruption: InterruptionConfig;
+export interface InternalTurnHandlingOptions extends TurnHandlingOptions {
+  endpointing: EndpointingOptions;
+  interruption: InterruptionOptions;
 }
 
-export const defaultTurnHandlingConfig: InternalTurnHandlingConfig = {
+export const defaultTurnHandlingOptions: InternalTurnHandlingOptions = {
   turnDetection: undefined,
-  interruption: defaultInterruptionConfig,
-  endpointing: defaultEndpointingConfig,
+  interruption: defaultInterruptionOptions,
+  endpointing: defaultEndpointingOptions,
 };

agents/src/voice/turn_config/utils.test.ts

@@ -3,9 +3,9 @@
 // SPDX-License-Identifier: Apache-2.0
 import { beforeAll, describe, expect, it } from 'vitest';
 import { initializeLogger } from '../../log.js';
-import { defaultEndpointingConfig } from './endpointing.js';
-import { defaultInterruptionConfig } from './interruption.js';
-import { defaultTurnHandlingConfig } from './turn_handling.js';
+import { defaultEndpointingOptions } from './endpointing.js';
+import { defaultInterruptionOptions } from './interruption.js';
+import { defaultTurnHandlingOptions } from './turn_handling.js';
 import { migrateLegacyOptions } from './utils.js';
 
 beforeAll(() => {
@@ -17,9 +17,9 @@ describe('migrateLegacyOptions', () => {
     const result = migrateLegacyOptions({});
 
     expect(result.options.turnHandling).toEqual({
-      turnDetection: defaultTurnHandlingConfig.turnDetection,
-      endpointing: defaultEndpointingConfig,
-      interruption: defaultInterruptionConfig,
+      turnDetection: defaultTurnHandlingOptions.turnDetection,
+      endpointing: defaultEndpointingOptions,
+      interruption: defaultInterruptionOptions,
     });
     expect(result.options.maxToolSteps).toBe(3);
     expect(result.options.preemptiveGeneration).toBe(false);
@@ -44,14 +44,14 @@ describe('migrateLegacyOptions', () => {
     expect(result.options.turnHandling.endpointing!.maxDelay).toBe(5000);
   });
 
-  it('should set interruption.mode to false when allowInterruptions is false', () => {
+  it('should set interruption.enabled to false when allowInterruptions is false', () => {
     const result = migrateLegacyOptions({
       options: {
         allowInterruptions: false,
       },
     });
 
-    expect(result.options.turnHandling.interruption!.mode).toBe(false);
+    expect(result.options.turnHandling.interruption!.enabled).toBe(false);
   });
 
   it('should give options precedence over voiceOptions when both are provided', () => {

agents/src/voice/turn_config/utils.ts

@@ -7,9 +7,9 @@ import {
   type InternalSessionOptions,
   defaultSessionOptions,
 } from '../agent_session.js';
-import { defaultEndpointingConfig } from './endpointing.js';
-import { defaultInterruptionConfig } from './interruption.js';
-import { type TurnHandlingConfig, defaultTurnHandlingConfig } from './turn_handling.js';
+import { defaultEndpointingOptions } from './endpointing.js';
+import { defaultInterruptionOptions } from './interruption.js';
+import { type TurnHandlingOptions, defaultTurnHandlingOptions } from './turn_handling.js';
 
 export function migrateLegacyOptions<UserData>(
   legacyOptions: AgentSessionOptions<UserData>,
@@ -50,7 +50,7 @@ export function migrateLegacyOptions<UserData>(
 
   const mergedOptions = structuredClone({ ...cloneableVoiceOptions, ...cloneableSessionOptions });
 
-  const turnHandling: TurnHandlingConfig = {
+  const turnHandling: TurnHandlingOptions = {
     interruption: {
       discardAudioIfUninterruptible: mergedOptions?.discardAudioIfUninterruptible,
       minDuration: mergedOptions?.minInterruptionDuration,
@@ -68,7 +68,7 @@ export function migrateLegacyOptions<UserData>(
   } as const;
 
   if (mergedOptions?.allowInterruptions === false) {
-    turnHandling.interruption.mode = false;
+    turnHandling.interruption.enabled = false;
   }
 
   const optionsWithDefaults = {
@@ -94,10 +94,10 @@ export function stripUndefined<T extends object>(obj: T): Partial<T> {
   return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined)) as Partial<T>;
 }
 
-export function mergeWithDefaults(config: TurnHandlingConfig) {
+export function mergeWithDefaults(config: TurnHandlingOptions) {
   return {
-    turnDetection: config.turnDetection ?? defaultTurnHandlingConfig.turnDetection,
-    endpointing: { ...defaultEndpointingConfig, ...stripUndefined(config.endpointing) },
-    interruption: { ...defaultInterruptionConfig, ...stripUndefined(config.interruption) },
+    turnDetection: config.turnDetection ?? defaultTurnHandlingOptions.turnDetection,
+    endpointing: { ...defaultEndpointingOptions, ...stripUndefined(config.endpointing) },
+    interruption: { ...defaultInterruptionOptions, ...stripUndefined(config.interruption) },
   } as const;
 }

plugins/livekit/src/turn_detector/base.ts

@@ -170,6 +170,14 @@ export abstract class EOUModel {
 
   #logger = log();
 
+  get model(): string {
+    return MODEL_REVISIONS[this.modelType];
+  }
+
+  get provider(): string {
+    return 'livekit';
+  }
+
   constructor(opts: EOUModelOptions) {
     const {
       modelType = 'en',